Schema Reference

Complete reference for all TypeScript types exported by form-builder-types.

FormSchema

The root object passed to FormRenderer and emitted by FormBuilder.

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for the form.
`title`	LocalizedString	Yes	Form heading, displayed above the fields.
`description`	LocalizedString	No	Optional subtitle shown below the title.
`fields`	FormFieldDefinition[]	Yes	Ordered list of field definitions. Rendered in ascending `order` value.
`submitLabel`	LocalizedString	No	Submit button label. Defaults to "Submit".
`settings`	FormSchemaSettings	No	Layout and behavior overrides.

FormFieldDefinition

Defines a single field in the form. Each entry in FormSchema.fields conforms to this type.

Field	Type	Required	Description
`id`	string	Yes	Unique field key. Used as the form data key in the submitted object.
`type`	FormFieldType	Yes	The widget type. See Field Types below.
`label`	LocalizedString	Yes	Visible label for the field.
`order`	number	Yes	Sort order. Fields are rendered in ascending order.
`placeholder`	LocalizedString	No	Input placeholder text. Applies to text, email, tel, number, textarea.
`description`	LocalizedString	No	Helper text shown below the input.
`required`	boolean	No	Marks the field as required. Adds JSON Schema `required` constraint.
`defaultValue`	unknown	No	Initial value pre-filled in the form.
`options`	FormFieldOption[]	No	Required for `select` and `radio` types.
`validation`	FormFieldValidation	No	Validation constraints. See Validation below.
`condition`	FormFieldCondition	No	Conditional display rule. Field is hidden unless the condition passes.

Field Types

All 13 supported field types, their JSON Schema mapping, and notes on behavior.

Type	Widget	JSON Schema	Notes
`text`	Input (text)	`type: "string"`	General single-line text input.
`number`	Input (number)	`type: "number"`	Numeric input. Supports `min`/`max` validation.
`email`	Input (email)	`type: "string", format: "email"`	Validates email format automatically.
`tel`	Input (tel)	`type: "string"`	Phone number input with `type="tel"` for mobile keyboards.
`select`	Select (dropdown)	`type: "string", enum: [...]`	Requires `options`. Uses shadcn Select component.
`checkbox`	Checkbox	`type: "boolean"`	Single boolean toggle. Submits `true`/`false`.
`radio`	RadioGroup	`type: "string", enum: [...]`	Requires `options`. Each option renders as a radio button.
`date`	Input (date)	`type: "string", format: "date"`	Native date picker. Submits ISO 8601 date string.
`textarea`	Textarea	`type: "string"`	Multi-line text. Supports `minLength`/`maxLength`.
`file`	Input (file)	`type: "string", format: "data-url"`	File picker. Value is a base64 data URL.
`heading`	h3 element	—	Display only. Does not collect data.
`paragraph`	p element	—	Display only. Renders `label` as a paragraph.
`separator`	hr / Separator	—	Display only. Visual divider between form sections.

Rows with a grey background are display-only fields — they are excluded from the submitted form data.

LocalizedString

LocalizedString is string | Record<string, string>. Use a plain string for single-language forms; use a locale map for multi-language forms.

// Plain string — always displayed as-is
label: "Full Name"

// Locale map — resolved at render time using the locale prop
label: { "en-US": "Full Name", "ko-KR": "이름", "ja-JP": "氏名" }

Resolution order: active locale → baseLocale → first available key → empty string.

Validation

The validation field accepts a FormFieldValidation object.

Field	Type	Applies to	Description
`minLength`	number	text, email, tel, textarea	Minimum character count.
`maxLength`	number	text, email, tel, textarea	Maximum character count.
`min`	number	number	Minimum numeric value.
`max`	number	number	Maximum numeric value.
`pattern`	string	text, tel	Regex pattern the value must match.
`customRule`	string	all input types	Key referencing a validator registered via `registerValidator`.

Custom validators

import { registerValidator, createCustomValidator } from '@/lib/form-builder-types/validation';

// Register once (e.g. in a layout or provider)
registerValidator('no-profanity', (value) => {
  if (typeof value === 'string' && value.includes('badword')) {
    return 'Please keep it respectful.';
  }
});

// Pass the validator to FormRenderer
<FormRenderer
  schema={schema}
  customValidate={createCustomValidator(schema)}
/>

Conditions

Set condition on a field to make it conditionally visible based on another field's current value.

// Show "otherDetails" only when "topic" equals "other"
{
  id: 'otherDetails',
  type: 'textarea',
  label: 'Please describe',
  order: 5,
  condition: {
    field: 'topic',   // the field id to watch
    operator: 'eq',
    value: 'other',
  }
}

Operators

Operator	Description	value required?
`eq`	Strict equality (`===`)	Yes
`neq`	Strict inequality (`!==`)	Yes
`gt`	Greater than. Numeric comparison.	Yes
`lt`	Less than. Numeric comparison.	Yes
`contains`	String includes the value.	Yes
`empty`	Field value is empty, null, or undefined.	No
`notEmpty`	Field value is not empty.	No

Settings

FormSchemaSettings is an optional object on the root FormSchema.

Field	Type	Default	Description
`layout`	"vertical" \| "horizontal"	"vertical"	Controls label position relative to the input.
`showProgressBar`	boolean	false	Displays a progress bar indicating form completion percentage.
`successMessage`	LocalizedString	—	Message shown after successful submission (if provided).