mui-schema-form-builder

Schema-driven, type-safe form builder for MUI + React Hook Form + Zod

Generate complex, production-ready forms from a plain JSON config. No boilerplate. No manual register calls. Full TypeScript inference from your Zod schema through to your onSubmit handler.

Features

Zero-config forms — one fields array, one schema, done
Type-safe submit — onSubmit data is fully typed from your Zod schema
MUI-native — built on @mui/material v9, not bolted on
Password input — FIELD_TYPE.PASSWORD with a built-in show/hide toggle (no icon library needed)
Combo input — FIELD_TYPE.COMBO_INPUT fuses a Select dropdown with a text/number/search input into a single compound field
Search input — FIELD_TYPE.SEARCH is a ready-to-use search field with a magnifying-glass icon pre-wired — no startAdornment config needed
Filter form — FilterForm fires onChange on every keystroke — no submit button, no schema required
Input adornments — startAdornment / endAdornment on TEXT and NUMBER fields for prefixes, suffixes, and icons
Form title — optional heading with alignment (titleAlign) and placement (titlePosition) control
Custom action buttons — replace Submit/Cancel/Reset with your own layout via renderActions
Multi-step wizard — FormWizard with per-step validation, completed-step navigation, and submit-error navigation
Async autocomplete — debounced fetch with built-in stale-response protection
Conditional fields — hide/show fields based on other field values
Performance — fields without visibleIf never re-render on sibling changes
Accessible — proper <label htmlFor>, aria-required, aria-invalid, aria-describedby
Virtualization — optional react-window support for 50+ field forms

Installation

npm install mui-schema-form-builder

Peer dependencies (install these if you don't have them):

npm install react react-dom @mui/material @emotion/react @emotion/styled \
            react-hook-form @hookform/resolvers zod

Optional (only needed when virtualize={true}):

npm install react-window

Quick Start

import { z } from 'zod';
import { FormBuilder, FIELD_TYPE } from 'mui-schema-form-builder';
import { ThemeProvider, createTheme } from '@mui/material';

const schema = z.object({
  name: z.string().min(2, 'Name is too short'),
  email: z.string().email('Invalid email'),
  age: z.number().min(18, 'Must be 18+'),
});

const fields = [
  { name: 'name', label: 'Full Name', type: FIELD_TYPE.TEXT, required: true },
  { name: 'email', label: 'Email Address', type: FIELD_TYPE.TEXT, required: true },
  { name: 'age', label: 'Age', type: FIELD_TYPE.NUMBER, required: true },
];

export default function App() {
  return (
    <ThemeProvider theme={createTheme()}>
      <FormBuilder
        fields={fields}
        schema={schema}
        onSubmit={(data) => {
          // data.name  → string  (TypeScript inferred from schema)
          // data.email → string
          // data.age   → number
          console.log(data);
        }}
      />
    </ThemeProvider>
  );
}

Field Schema Reference

Property	Type	Required	Description
`name`	`string`	✓	Field name — must match a key in your Zod schema
`label`	`string`	✓	Display label
`type`	`string`	✓	See field types below
`defaultValue`	`unknown`		Initial value
`placeholder`	`string`		Input placeholder
`required`	`boolean`		Shows asterisk, sets `aria-required`
`disabled`	`boolean`		Disables the field
`options`	`Option[]`		For SELECT, RADIO, CHECKBOX
`multiple`	`boolean`		Multi-select for SELECT and AUTOCOMPLETE
`grid`	`GridConfig`		MUI Grid `size` — e.g. `{ xs: 12, sm: 6 }`
`size`	`'small' \| 'medium'`		MUI component size
`fullWidth`	`boolean`		Full-width input (default `true`)
`min`	`number`		Min value — NUMBER only; also sets HTML `min`
`max`	`number`		Max value — NUMBER only; also sets HTML `max`
`step`	`number`		Step — NUMBER only; also sets HTML `step`
`rows`	`number`		Visible text rows — TEXTAREA only (default `4`)
`startAdornment`	`React.ReactNode`		Prefix node inside the input (TEXT, NUMBER). E.g. `"$"`, icon
`endAdornment`	`React.ReactNode`		Suffix node inside the input (TEXT, NUMBER). E.g. `"kg"`
`fetchOptions`	`(query: string) => Promise<Option[]>`		Async options for AUTOCOMPLETE
`visibleIf`	`(values: FieldValues) => boolean`		Hides field when returns `false`
`muiProps`	`Record<string, any>`		Extra props forwarded to the underlying MUI component
`section`	`string`		Groups consecutive same-section fields under a shared header
`selectOptions`	`Option[]`		Dropdown options — COMBO_INPUT only
`selectPosition`	`'start' \| 'end'`		Which side the Select appears on — COMBO_INPUT (default `'start'`)
`selectPlaceholder`	`string`		Placeholder shown when no option is selected — COMBO_INPUT only
`inputType`	`'text' \| 'number' \| 'search'`		HTML input type for the text portion — COMBO_INPUT (default `'text'`)
`selectWidth`	`number`		Width in px of the Select portion — COMBO_INPUT (default `120`)

Field Types

import { FIELD_TYPE } from 'mui-schema-form-builder';

FIELD_TYPE.TEXT;         // <input type="text">
FIELD_TYPE.TEXTAREA;     // <textarea> (multiline)
FIELD_TYPE.NUMBER;       // <input type="number">
FIELD_TYPE.DATE;         // <input type="date">
FIELD_TYPE.PASSWORD;     // Password input with show/hide toggle
FIELD_TYPE.SELECT;       // <Select> single or multi
FIELD_TYPE.AUTOCOMPLETE; // <Autocomplete> static or async
FIELD_TYPE.RADIO;        // <RadioGroup>
FIELD_TYPE.CHECKBOX;     // Boolean or checkbox group
FIELD_TYPE.ARRAY;        // Dynamic list with add/remove (useFieldArray)
FIELD_TYPE.DATE_PICKER;  // MUI DatePicker — register via createDatePickerInput
FIELD_TYPE.COMBO_INPUT;  // Fused Select + text/number/search — value shape: { select, input }
FIELD_TYPE.SEARCH;       // Text input with magnifying-glass icon pre-wired, type="search"

FilterForm

FilterForm is a reactive filter bar that fires onChange on every field change. No submit button, no Zod schema required — designed for search bars, filter sidebars, and toolbar filters.

import { FilterForm, FIELD_TYPE } from 'mui-schema-form-builder';

<FilterForm
  fields={[
    { name: 'search', label: 'Search', type: FIELD_TYPE.TEXT, placeholder: 'Search…', grid: { xs: 12, sm: 8 } },
    {
      name: 'status',
      label: 'Status',
      type: FIELD_TYPE.SELECT,
      options: [
        { label: 'All', value: '' },
        { label: 'Active', value: 'active' },
        { label: 'Inactive', value: 'inactive' },
      ],
      grid: { xs: 12, sm: 4 },
    },
  ]}
  onChange={(values) => console.log(values)}
  showReset
  defaultValues={{ search: '', status: '' }}
/>

Prop	Type	Default	Description
`fields`	`FieldConfig[]`	required	Field configuration
`onChange`	`(values: FieldValues) => void`	required	Called on every field change with the full state
`defaultValues`	`FieldValues`		Initial field values
`showReset`	`boolean`	`false`	Show a Reset button that restores `defaultValues`
`spacing`	`number`	`2`	MUI Grid spacing between fields
`resetText`	`string`	`'Reset'`	Reset button label

Combo Input

FIELD_TYPE.COMBO_INPUT fuses a Select dropdown with a text, number, or search input into a single compound field. The RHF value shape is { select, input }.

// Phone number — country code at start
{
  name: 'phone',
  label: 'Phone number',
  type: FIELD_TYPE.COMBO_INPUT,
  required: true,
  selectOptions: [
    { label: '+1', value: '+1' },
    { label: '+44', value: '+44' },
    { label: '+91', value: '+91' },
  ],
  selectPlaceholder: 'Code',
  selectWidth: 88,
  placeholder: '(555) 000-0000',
}

// Currency amount — selector at start, number input
{
  name: 'price',
  label: 'Price',
  type: FIELD_TYPE.COMBO_INPUT,
  selectOptions: [{ label: 'USD $', value: 'usd' }, { label: 'EUR €', value: 'eur' }],
  selectPlaceholder: 'Currency',
  selectWidth: 104,
  inputType: 'number',
  min: 0,
  placeholder: '0.00',
}

// Search with category — selector at end
{
  name: 'query',
  label: 'Search',
  type: FIELD_TYPE.COMBO_INPUT,
  selectPosition: 'end',
  selectOptions: [{ label: 'All', value: '' }, { label: 'Books', value: 'books' }],
  selectPlaceholder: 'Category',
  selectWidth: 130,
  inputType: 'search',
  placeholder: 'Search products…',
}

The Zod schema for a COMBO_INPUT field uses a nested object:

const schema = z.object({
  phone: z.object({
    select: z.string().min(1, 'Select a country code'),
    input: z.string().min(6, 'Enter a valid phone number'),
  }),
});

Note: When inputType: 'search', a magnifying-glass icon is automatically rendered as a start adornment — no extra configuration needed.

Search Input

FIELD_TYPE.SEARCH renders a text input with a magnifying-glass icon automatically pre-wired as the start adornment and type="search" set on the HTML input. No extra configuration required.

{
  name: 'search',
  label: 'Search',
  type: FIELD_TYPE.SEARCH,
  placeholder: 'Search products…',
}

Use it anywhere a FIELD_TYPE.TEXT field would go — especially inside FilterForm:

<FilterForm
  fields={[
    { name: 'search', label: 'Search', type: FIELD_TYPE.SEARCH, placeholder: 'Search…', grid: { xs: 12, sm: 8 } },
    { name: 'status', label: 'Status', type: FIELD_TYPE.SELECT, options: [...], grid: { xs: 12, sm: 4 } },
  ]}
  onChange={(values) => console.log(values)}
/>

You can still override the icon via startAdornment, or add an endAdornment (e.g. a clear button):

{ name: 'search', label: 'Search', type: FIELD_TYPE.SEARCH, endAdornment: <ClearButton /> }

Note: For a fused Select + search input (e.g. category + keyword), use FIELD_TYPE.COMBO_INPUT with inputType: 'search' instead.

Password Input

Use FIELD_TYPE.PASSWORD for a text input with a built-in show/hide toggle. The toggle uses an inline SVG icon — no @mui/icons-material dependency needed.

{
  name: 'password',
  label: 'Password',
  type: FIELD_TYPE.PASSWORD,
  required: true,
}

Input Adornments

Add a prefix or suffix decoration to TEXT and NUMBER fields via startAdornment and endAdornment. Pass any React node — a string, an icon, or an interactive element.

[
  {
    name: 'price',
    label: 'Price',
    type: FIELD_TYPE.NUMBER,
    startAdornment: '$',
    endAdornment: 'USD',
  },
  {
    name: 'username',
    label: 'Username',
    type: FIELD_TYPE.TEXT,
    startAdornment: '@',
  },
]

Note: PASSWORD fields have their own fixed end adornment (the visibility toggle). Setting endAdornment on a PASSWORD field has no effect.

Form Title

Add a heading to FormBuilder or FormWizard with the title, titleAlign, and titlePosition props.

<FormBuilder
  title="Edit Profile"
  titleAlign="left"        // 'left' | 'center' | 'right' — default: 'left'
  titlePosition="inside"   // 'inside' | 'above' — default: 'inside'
  ...
/>

titlePosition="inside" — the heading renders inside the Paper container above the fields.
titlePosition="above" — the heading renders outside the Paper, useful when you control the container styling.

Custom Action Buttons

Replace the default Submit / Cancel / Reset buttons with your own layout via renderActions.

FormBuilder

import type { FormBuilderActionsParams } from 'mui-schema-form-builder';

<FormBuilder
  onSubmit={fn}
  onCancel={cancelFn}
  onReset={resetFn}
  renderActions={({ isSubmitting, submit, cancel, reset }: FormBuilderActionsParams) => (
    <Stack direction="row" spacing={1} justifyContent="flex-end">
      {cancel && <Button onClick={cancel}>Discard</Button>}
      <Button variant="contained" onClick={submit} disabled={isSubmitting}>
        Save Changes
      </Button>
    </Stack>
  )}
/>

FormWizard

import type { FormWizardActionsParams } from 'mui-schema-form-builder';

<FormWizard
  steps={steps}
  schema={schema}
  onSubmit={fn}
  renderActions={({
    isSubmitting, isFirstStep, isLastStep, next, back, submit,
  }: FormWizardActionsParams) => (
    <Stack direction="row" spacing={2} justifyContent="space-between" width="100%">
      <Button onClick={back} disabled={isFirstStep}>← Back</Button>
      {isLastStep
        ? <Button variant="contained" onClick={submit}>Finish</Button>
        : <Button variant="contained" onClick={next}>Continue →</Button>
      }
    </Stack>
  )}
/>

Validation

Pass any Zod schema. The library uses @hookform/resolvers/zod internally:

const schema = z
  .object({
    password: z.string().min(8).regex(/[A-Z]/, 'Needs uppercase'),
    confirm: z.string(),
  })
  .refine((data) => data.password === data.confirm, {
    message: 'Passwords must match',
    path: ['confirm'],
  });

Control when validation runs:

<FormBuilder
  validationMode="onChange"  // 'onChange' | 'onBlur' | 'onTouched' | 'onSubmit'
  ...
/>

Conditional Fields

Only fields with visibleIf subscribe to form state changes. All other fields are isolated — typing in one field does not re-render its siblings.

const fields = [
  {
    name: 'status',
    label: 'Status',
    type: FIELD_TYPE.SELECT,
    options: [
      { label: 'Employed', value: 'employed' },
      { label: 'Student', value: 'student' },
    ],
  },
  {
    name: 'company',
    label: 'Company',
    type: FIELD_TYPE.TEXT,
    visibleIf: (values) => values['status'] === 'employed',
  },
];

Async Autocomplete

Built-in 300ms debounce and stale-response protection. If a later search resolves before an earlier one, the earlier response is discarded.

{
  name: 'country',
  label: 'Country',
  type: FIELD_TYPE.AUTOCOMPLETE,
  fetchOptions: async (query) => {
    const res = await fetch(`/api/countries?q=${query}`);
    const data = await res.json();
    return data.map((c: Country) => ({ label: c.name, value: c.code }));
  },
}

FormBuilder Props

Prop	Type	Default	Description
`fields`	`FieldConfig[]`	required	Field configuration
`schema`	`z.ZodType`	required*	Zod validation schema (*or `resolver`)
`resolver`	`Resolver`		react-hook-form resolver (alternative to `schema`)
`onSubmit`	`(data: z.infer<TSchema>) => void \| Promise<void>`	required	Typed submit handler
`onCancel`	`() => void`		Renders Cancel button when provided
`onReset`	`() => void`		Renders Reset button when provided
`onChange`	`(values: FieldValues) => void`		Called on every field value change
`onFieldChange`	`(name: string, value: unknown) => void`		Called when a single field changes
`submitText`	`string`	`'Submit'`	Submit button label
`cancelText`	`string`	`'Cancel'`	Cancel button label
`resetText`	`string`	`'Reset'`	Reset button label
`title`	`string`		Optional form heading
`titleAlign`	`'left' \| 'center' \| 'right'`	`'left'`	Horizontal alignment of the title
`titlePosition`	`'inside' \| 'above'`	`'inside'`	Whether the title is inside or above the Paper container
`renderActions`	`(params: FormBuilderActionsParams) => ReactNode`		Replace default buttons with a custom render
`readOnly`	`boolean`	`false`	Render all fields as display text
`labels`	`FormBuilderLabels`		Override built-in UI strings
`spacing`	`number`	`2`	MUI Grid spacing between fields
`virtualize`	`boolean`	`false`	Enable react-window for large forms
`validationMode`	`ValidationMode`	`'onTouched'`	When validation triggers
`sx`	`SxProps`		MUI sx prop for the outer Paper

TypeScript Tips

The generic propagates from schema → onSubmit automatically:

const schema = z.object({ name: z.string(), age: z.number() });

<FormBuilder
  schema={schema}
  fields={fields}
  onSubmit={(data) => {
    // data.name → string ✓
    // data.age  → number ✓
  }}
/>;

Memoize your fields array to prevent unnecessary recomputation of default values:

const fields = useMemo<FieldConfig[]>(
  () => [{ name: 'name', label: 'Name', type: FIELD_TYPE.TEXT }],
  [],
);

Accessibility

Every input has a proper <label htmlFor> association — clicking the label focuses the input
Required asterisk is aria-hidden (visual cue only)
Inputs have aria-required, aria-invalid, aria-describedby linked to error messages
Error messages have role="alert" for screen reader announcement
Radio groups and checkbox groups use <fieldset> + <legend> (WCAG 1.3.1)

Name		Name	Last commit message	Last commit date
Latest commit History 71 Commits
.github/workflows		.github/workflows
.storybook		.storybook
docs		docs
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
bun.lock		bun.lock
index.html		index.html
metadata.json		metadata.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

mui-schema-form-builder

Features

Installation

Quick Start

Field Schema Reference

Field Types

FilterForm

Combo Input

Search Input

Password Input

Input Adornments

Form Title

Custom Action Buttons

FormBuilder

FormWizard

Validation

Conditional Fields

Async Autocomplete

FormBuilder Props

TypeScript Tips

Accessibility

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

mui-schema-form-builder

Features

Installation

Quick Start

Field Schema Reference

Field Types

FilterForm

Combo Input

Search Input

Password Input

Input Adornments

Form Title

Custom Action Buttons

FormBuilder

FormWizard

Validation

Conditional Fields

Async Autocomplete

FormBuilder Props

TypeScript Tips

Accessibility

License

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages