Form

A form component library with validation, field management, and integration with various input types

Installation

Terminal

pnpm add @choice-ui/form

Import

Component.tsx

import { CheckboxAdapter, ChipsInputAdapter, InputAdapter, MultiSelectAdapter, NumericInputAdapter, RadioGroupAdapter, RangeAdapter, SegmentedAdapter, SelectAdapter, SwitchAdapter, TextareaAdapter, type FormValidator, type FieldValidator, type FieldValidators, type FormConfig, type FieldConfig, type FormState, type FieldState, type SimpleFormApi, type SimpleFieldApi, type FormContextValue, type FieldContextValue, type FormSubmitResult, type FormProps, type FormFieldProps, type FormSubmitProps, type FormFieldErrorProps, type FormFieldInfoProps, type FormFieldCommonProps, type FormFieldAdapterProps, type BaseAdapterProps, type AdapterPropsWithoutSize, type SelectAdapterPropsBase, type InputAdapterProps, type TextareaAdapterProps, type SelectAdapterProps, type MultiSelectAdapterProps, type CheckboxAdapterProps, type SwitchAdapterProps, type RangeAdapterProps, type NumericInputAdapterProps, type RadioGroupAdapterProps, type SegmentedAdapterProps, type ChipsInputAdapterProps, useForm } from "@choice-ui/form"

Basic

Demonstrates the basic usage of `form.Input` adapter with two validation timing strategies.

### Features

- **onChange validation**: Real-time validation as user types, ideal for instant feedback - **onBlur validation**: Validates when field loses focus, reduces validation frequency - **Custom label**: Supports ReactNode type for custom styling - **Error display**: Customize error appearance via `error` prop

### Tips

- Return `string` from validator to indicate error, `undefined` for valid - Errors are stored in `field.state.meta.errors` array - Use `useId()` to avoid field name conflicts in multiple instances

Form Result:

Textarea Adapter

Demonstrates various configuration options for `form.Textarea` adapter.

### Features

- **Auto-resize**: Control auto-expand range with `minRows` and `maxRows` - **Manual resize**: Enable drag-to-resize with `resize="handle"` - **Character count**: Display real-time character count via `description` - **Length validation**: Combine with validators for max length enforcement

### Tips

- Use `minRows/maxRows` for auto-height mode - Use `rows` for fixed-height mode - `description` supports dynamic content, perfect for character counters

Form Result:

Select Adapter

Demonstrates the `form.Select` adapter for single-selection dropdown.

### Features

- **Options array**: Define options with `{ label, value }` objects - **Dividers**: Add visual separation with `{ divider: true }` - **Placeholder**: Show hint text when no selection - **Match trigger width**: Use `matchTriggerWidth` to align dropdown width

### Tips

- Options without `value` are rendered as labels/headers - Validate selection with `onChange` validator - Access selected value via `field.state.value`

Form Result:

Multi Select Adapter

Demonstrates the `form.MultiSelect` adapter for multi-selection dropdown.

### Features

- **Multiple selection**: Select multiple options from dropdown - **Array value**: Value is `string[]` type - **Dividers & labels**: Organize options with dividers and group labels - **Min/max validation**: Enforce selection count limits

### Tips

- Default value should be an array: `defaultValues: { roles: ["admin"] }` - Cast value to `string[]` when accessing: `field.state.value as string[]` - Validate array length for required selections

Form Result:

Chips Input Adapter

Demonstrates the `form.ChipsInput` adapter for tag/chip input.

### Features

- **Tag management**: Add tags by pressing Enter, remove by clicking X - **Array value**: Value is `string[]` type like MultiSelect - **Backspace removal**: Delete last tag with backspace when input is empty - **Blur-to-add**: Automatically converts input to tag on blur

### Tips

- Validate tag count with array length checks - Great for keywords, labels, or email recipients - Combine with `allowDuplicates={false}` to prevent duplicate tags

Form Result:

Checkbox Adapter

Demonstrates the `form.Checkbox` adapter for boolean toggle.

### Features

- **Boolean value**: Value is `true` or `false` - **Required validation**: Ensure checkbox is checked before submit - **Label support**: Display label text next to checkbox

### Tips

- Use for terms acceptance, opt-in features, or boolean flags - Validate with `if (!value) return "Error message"` - Default value should be boolean: `defaultValues: { agreed: false }`

Form Result:

Radio Group Adapter

Demonstrates the `form.RadioGroup` adapter for single selection from visible options.

### Features

- **Single selection**: Only one option can be selected at a time - **Visible options**: All options displayed at once (unlike Select dropdown) - **Options array**: Define with `{ label, value }` objects

### Tips

- Use when options are few (2-5) and should all be visible - Use Select for longer option lists - Great for payment methods, shipping options, or plan selection

Form Result:

Switch Adapter

Demonstrates the `form.Switch` adapter for on/off toggle.

### Features

- **Boolean value**: Same as Checkbox but with toggle UI - **Visual distinction**: Better for settings that take effect immediately - **Label support**: Display label next to switch

### Tips

- Use for settings, preferences, or feature toggles - Prefer Switch over Checkbox for "on/off" semantics - Works identically to Checkbox in terms of value handling

Form Result:

Range Adapter

Demonstrates the `form.Range` adapter for numeric slider input.

### Features

- **Numeric value**: Value is `number` type - **Min/Max bounds**: Set range with `min` and `max` props - **Step control**: Define increment with `step` prop - **Visual feedback**: Shows current value on slider

### Tips

- Great for volume, brightness, or quantity selection - Validate minimum/maximum values with onChange validator - Consider NumericInput for precise number entry

Form Result:

Numeric Input Adapter

Demonstrates the `form.NumericInput` adapter for precise numeric input.

### Features

- **Numeric value**: Value is `number` type with precise input - **Increment buttons**: Built-in +/- buttons for adjustment - **Prefix/Suffix slots**: Add icons or units with `NI.Prefix` and `NI.Suffix` - **Children composition**: Supports compound component pattern

### Tips

- Use for age, quantity, price, or any precise number input - Validate range with `if (value < min || value > max)` - Import as `NumericInput as NI` for cleaner slot access

Form Result:

Segmented Adapter

Demonstrates the `form.Segmented` adapter for horizontal button-style selection.

### Features

- **Single selection**: Select one option from horizontal buttons - **Compact UI**: All options visible in a single row - **Options array**: Use `{ content, value }` for each option

### Tips

- Use for view toggles, time periods, or small option sets - `content` can be string or ReactNode for icons - Best for 2-4 options that fit horizontally

Form Result:

Basic Form

A complete form example combining multiple field types with TanStack Form.

### Features

- **Multiple adapters**: Combines Input and Select in one form - **Form submission**: Full submit flow with result display - **Default values**: Pre-populate form with initial data

### Tips

- Always call `e.preventDefault()` and `e.stopPropagation()` in onSubmit - Use `form.handleSubmit()` to trigger form submission - Access all values in `onSubmit` callback via `value` parameter

Form Result:

With Description

## Form with Description

Demonstrates how to add helper text below form fields.

### Features

- **String description**: Simple text hint below field - **ReactNode description**: Complex content with links, badges, etc. - **Dynamic description**: Update based on field state (e.g., character count)

### Tips

- Use description for hints, requirements, or additional context - Combine with validation errors for complete field feedback - ReactNode allows inline links with `LinkButton`

Form Result:

With Validation

## Form with Validation

Demonstrates inline validation with custom rules and error display.

### Features

- **Password validation**: Length and complexity requirements - **Confirm password**: Cross-field validation - **Numeric validation**: Range and format checks - **Real-time feedback**: Errors update as user types

### Tips

- Access other field values via `form.state.values.fieldName` - Return error string or `undefined` from validators - Join multiple errors with `field.state.meta.errors.join(", ")`

Form Result:

With Schema Validation

## Form with Zod Schema Validation

Demonstrates integration with Zod for schema-based validation.

### Features

- **Schema-level validation**: Define all rules in one Zod schema - **Type inference**: Automatic TypeScript types from schema - **Complex rules**: Email format, URL validation, optional fields - **Form state display**: Shows canSubmit, isDirty, isValid status

### Tips

- Pass Zod schema to `validators.onChange` and `validators.onBlur` - Use `z.string().optional().or(z.literal(""))` for optional string fields - Format nested Zod errors with custom `formatErrors` helper

Schema Validation

Use Zod Schema to validate the form, support complex validation rules

Form state:

Can submit:

Yes

Is dirty:

Validating:

Submitting:

Valid:

Yes

With Async Initial Values

## Form with Async Initial Values

Demonstrates loading form data from an API and editing existing records.

### Features

- **Async data loading**: Fetch initial values from API/database - **Loading state**: Show loading indicator while fetching - **Error handling**: Display error message with retry option - **User switching**: Load different records dynamically - **Form reset**: Reload data after successful update

### Tips

- Use `form.setFieldValue()` to update form when async data arrives - Add `key` prop to form to force re-render on record change - Handle loading/error states outside the form component

Async Initial Values Example

Demonstrate how to asynchronously load the initial values of the form, commonly used in editing existing data scenarios

Select user to edit:

Loading user data...

Please wait

With Array Fields

## Form with Array Fields

Demonstrates dynamic arrays of fields - both simple strings and complex objects.

### Features

- **Simple arrays**: List of strings (e.g., skills/tags) - **Object arrays**: Complex items with multiple fields (e.g., hobbies, contacts) - **Dynamic add/remove**: Push and remove items at runtime - **Nested validation**: Validate individual array items

### Tips

- Use `mode="array"` on Field for array operations - Access array methods: `field.pushValue()`, `field.removeValue(index)` - Name nested fields as `arrayName[index].property` - Provide unique `key` for each array item (avoid using index alone)

Array Form Example

Demonstrate how to handle array-type form fields, including simple arrays and object arrays

Form status:

Can submit: Yes

Is dirty: No

Is submitting: No

Is valid: Yes

Current form data:

{
  "name": "",
  "skills": [],
  "hobbies": [
    {
      "name": "",
      "description": "",
      "yearsOfExperience": 0
    }
  ],
  "contacts": [
    {
      "type": "email",
      "value": "",
      "isPrimary": true
    },
    {
      "type": "phone",
      "value": "",
      "isPrimary": false
    }
  ]
}

With Linked Fields

## Form with Linked Fields

Demonstrates cross-field validation where changing one field triggers validation of another.

### Features

- **Password confirmation**: Re-validate confirm when password changes - **Email confirmation**: Similar pattern for email change flow - **onChangeListenTo**: Specify which fields trigger re-validation - **Cross-field access**: Read other field values in validators

### Tips

- Use `onChangeListenTo: ["fieldName"]` to listen to other fields - Access other values via `fieldApi.form.getFieldValue("fieldName")` - Great for confirm fields, dependent dropdowns, or calculated values

Linked fields example

Demonstrates how to link two fields, when one field value changes, the validation of the other field will be re-run

Form status:

Can submit: Yes

Is dirty: No

Is submitting: No

Is valid: Yes

Field linking status:

• Confirm password listen: password field

• New email listen: email field

• Confirm new email listen: newEmail field

Current form data:

{
  "username": "",
  "email": "",
  "password": "",
  "confirmPassword": "",
  "newEmail": "",
  "confirmNewEmail": ""
}

With Reactivity

## Form with Reactivity Patterns

Demonstrates reactive subscriptions to form state using `useStore` and `form.Subscribe`.

### Features

- **useStore hook**: Subscribe to specific form values outside JSX - **form.Subscribe**: Reactive component that re-renders on value changes - **Conditional fields**: Show/hide fields based on form state - **Computed values**: Calculate derived values from form data - **Status badges**: Display real-time form status

### Tips

- `useStore(form.store, (state) => state.values.field)` for single value - `form.Subscribe selector={...}` for JSX-embedded subscriptions - Use precise selectors to minimize re-renders - Great for dynamic pricing, conditional sections, or live previews

Reactive subscription example

Demonstrates how to use useStore and form.Subscribe to access reactive form values

useStore subscription example

• Current user type: Personal user

• Calculate price: $10/month

• Form status:

Can submit

Real-time form status (form.Subscribe):

Can submit: Yes

Is dirty: No

Is valid: Yes

Is submitting: No

Real-time form data (form.Subscribe):

{
  "userType": "personal",
  "name": "",
  "email": "",
  "company": "",
  "website": "",
  "plan": "basic",
  "newsletter": false,
  "notifications": {
    "email": true,
    "sms": false,
    "push": true
  },
  "budget": 1000
}

Performance optimization:

• form.Subscribe: Suitable for responsive rendering, only re-rendering when the subscribed value changes

• Selector: Use precise selectors to avoid unnecessary re-rendering

• Multiple value subscription: Can subscribe to multiple values, reducing subscription count

With Listeners

## Form with Listeners API

Demonstrates the Listeners API for side effects and cascading field updates.

### Features

- **Cascading selects**: Country → Province → City with auto-reset - **User type switching**: Reset related fields when type changes - **Linked checkboxes**: Auto-subscribe when enabling notifications - **Activity logging**: Track all field changes for debugging - **Lifecycle events**: onMount, onChange, onBlur handlers

### Tips

- Listeners are for side effects, validators are for validation - Use `form.setFieldValue()` inside listeners to update other fields - `onChange` listener receives the new value as parameter - Perfect for dependent dropdowns, auto-fill, or analytics tracking

Listeners API example

Demonstrates how to use Listeners API to handle side effects and cascading logic between fields

Activity log

No activity

Current form data preview:

{
  "country": "",
  "province": "",
  "city": "",
  "userType": "individual",
  "personalInfo": {
    "firstName": "",
    "lastName": "",
    "idNumber": ""
  },
  "companyInfo": {
    "companyName": "",
    "taxId": "",
    "industry": ""
  },
  "organizationInfo": {
    "orgName": "",
    "orgType": "",
    "registrationNumber": ""
  },
  "email": "",
  "phone": "",
  "newsletter": false,
  "notifications": {
    "email": true,
    "sms": false
  }
}

Listener events description:

• onChange: Triggered when the field value changes (most commonly used)

• onBlur: Triggered when the field loses focus

• onMount: Triggered when the field is first mounted

• onSubmit: Triggered when the form is submitted

With Custom Errors

## Form with Custom Errors

Demonstrates advanced error handling with structured error objects and custom displays.

### Features

- **Error types**: String, object, array, boolean, and number errors - **Severity levels**: Error, warning, and info severity - **Password strength**: Visual strength meter with requirement checklist - **File validation**: Multi-issue file validation with details - **Server errors**: Async validation with server-side checks - **Rich error display**: Custom rendering for complex error objects

### Tips

- Return structured objects: `{ type, message, severity, code, details }` - Use `onBlurAsync` for server-side validation - Create custom `formatErrors` helper for rich error rendering - Different error types support different UX patterns

Custom error handling example

Demonstrates how to use TanStack Form's flexible error handling mechanism, supporting multiple error types and custom error display

Supported error types:

• String: The most common error type

• Object: Contains type, message, severity, and other detailed information

• Array: A collection of multiple errors

• Boolean: true means error, false means correct

• Number: Non-zero values mean error

• undefined/null: Means no error

API reference

BaseAdapter	Type	Default
className	string \| undefined	-
description	ReactNode	-
error	ReactNode	-
htmlFor	string \| undefined	-
label	ReactNode	-
legendMode	boolean \| undefined	false
CheckboxAdapter	Type	Default
value	boolean \| undefined	-
readOnly	boolean \| undefined	-
className	string \| undefined	-
variant	undefined \| "default" \| "accent" \| "outline"	-
focused	boolean \| undefined	-
mixed	boolean \| undefined	-
onChange	(value: T) => void	-
onBlur	(() => void) \| undefined	-
onFocus	(() => void) \| undefined	-
label	ReactNode	-
size	undefined \| "default" \| "large"	-
description	ReactNode	-
error	ReactNode	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
createCheckboxAdapter	Type	Default
value	boolean \| undefined	-
readOnly	boolean \| undefined	-
className	string \| undefined	-
variant	undefined \| "default" \| "accent" \| "outline"	-
focused	boolean \| undefined	-
mixed	boolean \| undefined	-
onChange	((value: T) => void) \| undefined	-
onBlur	(() => void) \| undefined	-
onFocus	(() => void) \| undefined	-
label	ReactNode	-
size	undefined \| "default" \| "large"	-
description	ReactNode	-
error	ReactNode	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
ChipsInputAdapter	Type	Default
disabled	boolean \| undefined	-
placeholder	string \| undefined	-
readOnly	boolean \| undefined	-
id	string \| undefined	-
allowDuplicates	boolean \| undefined	-
onAdd	((value: string) => void) \| undefined	-
onRemove	((value: string) => void) \| undefined	-
renderChip	((props: RenderChipProps) => ReactNode) \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	(value: T[]) => void	-
onChangeAsync	((value: T[]) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	T[]	-
createChipsInputAdapter	Type	Default
disabled	boolean \| undefined	-
placeholder	string \| undefined	-
readOnly	boolean \| undefined	-
id	string \| undefined	-
allowDuplicates	boolean \| undefined	-
onAdd	((value: string) => void) \| undefined	-
onRemove	((value: string) => void) \| undefined	-
renderChip	((props: RenderChipProps) => ReactNode) \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	((value: T[]) => void) \| undefined	-
onChangeAsync	((value: T[]) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	T[] \| undefined	-
InputAdapter	Type	Default
selected	boolean \| undefined	-
className	string \| undefined	-
focusSelection	undefined \| "none" \| "all" \| "end"	-
onIsEditingChange	((isEditing: boolean) => void) \| undefined	-
variant	undefined \| "default" \| "light" \| "dark" \| "reset"	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	(value: T) => void	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	string	-
createInputAdapter	Type	Default
selected	boolean \| undefined	-
className	string \| undefined	-
focusSelection	undefined \| "none" \| "all" \| "end"	-
onIsEditingChange	((isEditing: boolean) => void) \| undefined	-
variant	undefined \| "default" \| "light" \| "dark" \| "reset"	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	((value: T) => void) \| undefined	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	string \| undefined	-
MultiSelectAdapter	Type	Default
disabled	boolean \| undefined	-
open	boolean \| undefined	-
placeholder	string \| undefined	-
readOnly	boolean \| undefined	-
className	string \| undefined	-
renderChip	((props: { disabled?: boolean \| undefined; displayValue: string; index: number; onRemove?: ((e: MouseEvent<HTMLButtonElement, MouseEvent>) => void) \| undefined; value: string; }) => ReactNode) \| undefined	-
variant	undefined \| "default" \| "light" \| "reset"	-
chipVariant	undefined \| "default" \| "accent" \| "success" \| "rest"	-
closeOnSelect	boolean \| undefined	-
focusManagerProps	FloatingFocusManagerProps \| undefined	-
getDisplayValue	((value: string) => string) \| undefined	-
i18n	{ maxSelectionMessage?: ((maxSelection: number) => string) \| undefined; minSelectionMessage?: ((minSelection: number) => string) \| undefined; } \| undefined	-
matchTriggerWidth	boolean \| undefined	-
maxChips	number \| undefined	-
maxSelection	number \| undefined	-
minSelection	number \| undefined	-
onOpenChange	((open: boolean) => void) \| undefined	-
placement	undefined \| "top" \| "right" \| "bottom" \| "left" \| "top-start" \| "top-end" \| "right-start" \| "right-end" \| "bottom-start" \| "bottom-end" \| "left-start" \| "left-end"	-
portalId	string \| undefined	-
root	HTMLElement \| null \| undefined	-
showValidationMessage	boolean \| undefined	-
values	string[] \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	(value: T[]) => void	-
onChangeAsync	((value: T[]) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	T[]	-
name	string \| undefined	-
options	SelectOption<T>[] \| undefined	[]
createMultiSelectAdapter	Type	Default
disabled	boolean \| undefined	-
open	boolean \| undefined	-
placeholder	string \| undefined	-
readOnly	boolean \| undefined	-
className	string \| undefined	-
renderChip	((props: { disabled?: boolean \| undefined; displayValue: string; index: number; onRemove?: ((e: MouseEvent<HTMLButtonElement, MouseEvent>) => void) \| undefined; value: string; }) => ReactNode) \| undefined	-
variant	undefined \| "default" \| "light" \| "reset"	-
chipVariant	undefined \| "default" \| "accent" \| "success" \| "rest"	-
closeOnSelect	boolean \| undefined	-
focusManagerProps	FloatingFocusManagerProps \| undefined	-
getDisplayValue	((value: string) => string) \| undefined	-
i18n	{ maxSelectionMessage?: ((maxSelection: number) => string) \| undefined; minSelectionMessage?: ((minSelection: number) => string) \| undefined; } \| undefined	-
matchTriggerWidth	boolean \| undefined	-
maxChips	number \| undefined	-
maxSelection	number \| undefined	-
minSelection	number \| undefined	-
onOpenChange	((open: boolean) => void) \| undefined	-
placement	undefined \| "top" \| "right" \| "bottom" \| "left" \| "top-start" \| "top-end" \| "right-start" \| "right-end" \| "bottom-start" \| "bottom-end" \| "left-start" \| "left-end"	-
portalId	string \| undefined	-
root	HTMLElement \| null \| undefined	-
showValidationMessage	boolean \| undefined	-
values	string[] \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	((value: T[]) => void) \| undefined	-
onChangeAsync	((value: T[]) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	T[] \| undefined	-
name	string \| undefined	-
options	SelectOption<T>[] \| undefined	-
NumericInputAdapter	Type	Default
size	undefined \| "default" \| "large"	-
defaultValue	NumericInputValue \| undefined	-
disabled	boolean \| undefined	-
max	number \| undefined	-
min	number \| undefined	-
readOnly	boolean \| undefined	-
selected	boolean \| undefined	-
step	number \| undefined	-
className	string \| undefined	-
id	string \| undefined	-
onIsEditingChange	((isEditing: boolean) => void) \| undefined	-
variant	undefined \| "default" \| "light" \| "dark" \| "reset"	-
classNames	{ container?: string \| undefined; input?: string \| undefined; } \| undefined	-
tooltip	TooltipProps \| undefined	-
triggerRef	RefObject<HTMLDivElement> \| ((el: HTMLDivElement \| null) => void) \| undefined	-
decimal	number \| undefined	-
expression	string \| undefined	-
focused	boolean \| undefined	-
handlerPressed	boolean \| undefined	-
handlerProps	Record<string, unknown> \| undefined	-
onEmpty	(() => void) \| undefined	-
onPressEnd	(((event: PressEvent) => void) & ((e: PointerEvent) => void)) \| undefined	-
onPressStart	(((event: PressEvent) => void) & ((e: PointerEvent) => void)) \| undefined	-
shiftStep	number \| undefined	-
value	number	-
onChange	(value: T) => void	-
onBlur	(() => void) \| undefined	-
onFocus	(() => void) \| undefined	-
label	ReactNode	-
description	ReactNode	-
error	ReactNode	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
createNumericInputAdapter	Type	Default
size	undefined \| "default" \| "large"	-
defaultValue	NumericInputValue \| undefined	-
disabled	boolean \| undefined	-
max	number \| undefined	-
min	number \| undefined	-
readOnly	boolean \| undefined	-
selected	boolean \| undefined	-
step	number \| undefined	-
className	string \| undefined	-
id	string \| undefined	-
onIsEditingChange	((isEditing: boolean) => void) \| undefined	-
variant	undefined \| "default" \| "light" \| "dark" \| "reset"	-
classNames	{ container?: string \| undefined; input?: string \| undefined; } \| undefined	-
tooltip	TooltipProps \| undefined	-
triggerRef	RefObject<HTMLDivElement> \| ((el: HTMLDivElement \| null) => void) \| undefined	-
decimal	number \| undefined	-
expression	string \| undefined	-
focused	boolean \| undefined	-
handlerPressed	boolean \| undefined	-
handlerProps	Record<string, unknown> \| undefined	-
onEmpty	(() => void) \| undefined	-
onPressEnd	(((event: PressEvent) => void) & ((e: PointerEvent) => void)) \| undefined	-
onPressStart	(((event: PressEvent) => void) & ((e: PointerEvent) => void)) \| undefined	-
shiftStep	number \| undefined	-
value	number \| undefined	-
onChange	((value: T) => void) \| undefined	-
onBlur	(() => void) \| undefined	-
onFocus	(() => void) \| undefined	-
label	ReactNode	-
description	ReactNode	-
error	ReactNode	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
RadioGroupAdapter	Type	Default
readOnly	boolean \| undefined	-
variant	undefined \| "default" \| "accent" \| "outline"	-
options	{ disabled?: boolean \| undefined; label: string; value: string; }[] \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	(value: T) => void	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	string	-
createRadioGroupAdapter	Type	Default
readOnly	boolean \| undefined	-
variant	undefined \| "default" \| "accent" \| "outline"	-
options	{ disabled?: boolean \| undefined; label: string; value: string; }[] \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	((value: T) => void) \| undefined	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	string \| undefined	-
RangeAdapter	Type	Default
defaultValue	number \| undefined	-
disabled	boolean \| undefined	-
max	number \| undefined	-
min	number \| undefined	-
readOnly	boolean \| undefined	-
step	number \| undefined	-
className	string \| undefined	-
connectsClassName	{ negative?: string \| undefined; positive?: string \| undefined; } \| undefined	-
onChangeEnd	(() => void) \| undefined	-
onChangeStart	(() => void) \| undefined	-
thumbSize	number \| undefined	-
trackSize	{ height?: number \| undefined; width?: number \| "auto" \| undefined; } \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	(value: T) => void	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	number	-
createRangeAdapter	Type	Default
defaultValue	number \| undefined	-
disabled	boolean \| undefined	-
max	number \| undefined	-
min	number \| undefined	-
readOnly	boolean \| undefined	-
step	number \| undefined	-
className	string \| undefined	-
connectsClassName	{ negative?: string \| undefined; positive?: string \| undefined; } \| undefined	-
onChangeEnd	(() => void) \| undefined	-
onChangeStart	(() => void) \| undefined	-
thumbSize	number \| undefined	-
trackSize	{ height?: number \| undefined; width?: number \| "auto" \| undefined; } \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	((value: T) => void) \| undefined	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	number \| undefined	-
SegmentedAdapter	Type	Default
disabled	boolean \| undefined	-
readOnly	boolean \| undefined	-
className	string \| undefined	-
variant	undefined \| "default" \| "light" \| "dark" \| "reset"	-
tooltip	TooltipProps \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	(value: T) => void	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	string	-
options	SegmentedOption<T>[] \| undefined	-
createSegmentedAdapter	Type	Default
disabled	boolean \| undefined	-
readOnly	boolean \| undefined	-
className	string \| undefined	-
variant	undefined \| "default" \| "light" \| "dark" \| "reset"	-
tooltip	TooltipProps \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	((value: T) => void) \| undefined	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	string \| undefined	-
options	SegmentedOption<T>[] \| undefined	-
SelectAdapter	Type	Default
disabled	boolean \| undefined	-
open	boolean \| undefined	-
readOnly	boolean \| undefined	-
className	string \| undefined	-
variant	undefined \| "default" \| "light" \| "reset"	-
focusManagerProps	Partial<FloatingFocusManagerProps> \| undefined	-
matchTriggerWidth	boolean \| undefined	-
onOpenChange	((open: boolean) => void) \| undefined	-
placement	undefined \| "bottom-start" \| "bottom-end"	-
portalId	string \| undefined	-
root	HTMLElement \| null \| undefined	-
closeOnEscape	boolean \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	(value: T) => void	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	string	-
name	string \| undefined	-
options	SelectOption<T>[] \| undefined	[]
placeholder	string \| undefined	-
createSelectAdapter	Type	Default
disabled	boolean \| undefined	-
open	boolean \| undefined	-
readOnly	boolean \| undefined	-
className	string \| undefined	-
variant	undefined \| "default" \| "light" \| "reset"	-
focusManagerProps	Partial<FloatingFocusManagerProps> \| undefined	-
matchTriggerWidth	boolean \| undefined	-
onOpenChange	((open: boolean) => void) \| undefined	-
placement	undefined \| "bottom-start" \| "bottom-end"	-
portalId	string \| undefined	-
root	HTMLElement \| null \| undefined	-
closeOnEscape	boolean \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	((value: T) => void) \| undefined	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	string \| undefined	-
name	string \| undefined	-
options	SelectOption<T>[] \| undefined	-
placeholder	string \| undefined	-
SwitchAdapter	Type	Default
readOnly	boolean \| undefined	-
className	string \| undefined	-
variant	undefined \| "default" \| "accent" \| "outline"	-
focused	boolean \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	(value: T) => void	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	boolean	-
createSwitchAdapter	Type	Default
readOnly	boolean \| undefined	-
className	string \| undefined	-
variant	undefined \| "default" \| "accent" \| "outline"	-
focused	boolean \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	((value: T) => void) \| undefined	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	boolean \| undefined	-
TextareaAdapter	Type	Default
selected	boolean \| undefined	-
className	string \| undefined	-
focusSelection	undefined \| "none" \| "all" \| "end"	"all"
onIsEditingChange	((isEditing: boolean) => void) \| undefined	-
variant	undefined \| "default" \| "light" \| "dark" \| "reset"	"default"
allowNewline	boolean \| undefined	true
contentRef	RefObject<HTMLDivElement> \| undefined	-
lineHeight	number \| undefined	16
maxRows	number \| undefined	undefined (no maximum)
minRows	number \| undefined	3
padding	number \| undefined	4 (py-1)
resize	false \| "auto" \| "handle" \| undefined	"auto"
scrollRef	RefObject<HTMLDivElement> \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	(value: T) => void	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	string	-
createTextareaAdapter	Type	Default
selected	boolean \| undefined	-
className	string \| undefined	-
focusSelection	undefined \| "none" \| "all" \| "end"	"all"
onIsEditingChange	((isEditing: boolean) => void) \| undefined	-
variant	undefined \| "default" \| "light" \| "dark" \| "reset"	"default"
allowNewline	boolean \| undefined	true
contentRef	RefObject<HTMLDivElement> \| undefined	-
lineHeight	number \| undefined	16
maxRows	number \| undefined	undefined (no maximum)
minRows	number \| undefined	3
padding	number \| undefined	4 (py-1)
resize	false \| "auto" \| "handle" \| undefined	"auto"
scrollRef	RefObject<HTMLDivElement> \| undefined	-
description	ReactNode	-
error	ReactNode	-
label	ReactNode	-
onBlur	(() => void) \| undefined	-
onBlurAsync	(() => void) \| undefined	-
onBlurAsyncDebounceMs	number \| undefined	-
onChange	((value: T) => void) \| undefined	-
onChangeAsync	((value: T) => void) \| undefined	-
onChangeAsyncDebounceMs	number \| undefined	-
onFocus	(() => void) \| undefined	-
onFocusAsync	(() => void) \| undefined	-
onFocusAsyncDebounceMs	number \| undefined	-
size	undefined \| "default" \| "large"	-
value	string \| undefined	-

Form

Installation

Import

Basic

Textarea Adapter

Select Adapter

Multi Select Adapter

Chips Input Adapter

Checkbox Adapter

Radio Group Adapter

Switch Adapter

Range Adapter

Numeric Input Adapter

Segmented Adapter

Basic Form

With Description

With Validation

With Schema Validation

Schema Validation

With Async Initial Values

Async Initial Values Example

With Array Fields

Array Form Example

With Linked Fields

Linked fields example

Password validation example

Email validation example

With Reactivity

Reactive subscription example

useStore subscription example

form.Subscribe subscription example

Notification settings

With Listeners

Listeners API example

Activity log

Cascading select example

User type switch example

Personal information

Notification settings example

Contact information

With Custom Errors

Custom error handling example

Composite validation example

Password strength validation example

File validation example

Array error example

Number validation example

API reference