Fields
Complete reference for all available form field components.
Field Types
InputField
The most common field type for text input.
<InputField
name="email"
label="Email"
description="We'll never share your email."
tooltip="Used for account notifications"
type="email"
placeholder="Enter your email"
/>
// Numeric coercion (Zod-friendly): when type="number", value is coerced to number
<InputField
name="qty"
label="Quantity"
description="Must be a number"
tooltip="Must be a number"
type="number"
/>
// Or force coercion regardless of type via valueAsNumber
<InputField
name="qty"
label="Quantity"
description="Must be a number"
tooltip="Must be a number"
valueAsNumber
/>Extends all native HTML input props plus:
| Prop | Type | Description |
|---|---|---|
name | string | Form field name (simple API) |
field | FieldApi | Field instance (advanced API) |
label | React.ReactNode | Field label |
description | React.ReactNode | Helper text shown under the label |
tooltip | React.ReactNode | Inline info icon content (shows on hover/focus) |
size | "sm" | "md" | "lg" | Input and field chrome size |
variant | "default" | "inline" | Input visual variant |
children | React.ReactNode | Additional content (help text, etc.) |
valueAsNumber | boolean | Coerce to number on change; implied when type="number" |
TextareaField
Multi-line text input for longer content.
<TextareaField
name="message"
label="Message"
placeholder="Type your message..."
description="We'll never share your message."
tooltip="Used for account notifications"
rows={5}
/>Extends all native HTML textarea props plus:
| Prop | Type | Description |
|---|---|---|
name | string | Form field name (simple API) |
field | FieldApi | Field instance (advanced API) |
label | React.ReactNode | Field label |
description | React.ReactNode | Helper text under the label |
tooltip | React.ReactNode | Inline info icon content |
size | "sm" | "md" | "lg" | Textarea and field chrome size |
placeholder | string | Placeholder text |
children | React.ReactNode | Additional content (help text, etc.) |
CheckboxField
Single checkbox for boolean values.
<CheckboxField
name="agree"
label="I agree to the terms"
description="We'll never share your message."
tooltip="Used for account notifications"
/>| Prop | Type | Description |
|---|---|---|
name | string | Form field name (simple API) |
field | BoolFieldApi | Field instance (advanced API) |
label | React.ReactNode | Checkbox label |
description | React.ReactNode | Helper text under the label |
tooltip | React.ReactNode | Inline info icon content |
size | "sm" | "md" | "lg" | Checkbox and field chrome size |
className | string | Additional classes |
SwitchField
Toggle switch for boolean values.
<SwitchField
name="notifications"
label="Enable notifications"
description="We'll never share your message."
tooltip="Used for account notifications"
/>| Prop | Type | Description |
|---|---|---|
name | string | Form field name (simple API) |
field | BoolFieldApi | Field instance (advanced API) |
label | React.ReactNode | Switch label |
description | React.ReactNode | Helper text under the label |
tooltip | React.ReactNode | Inline info icon content |
size | "sm" | "md" | "lg" | Switch and field chrome size |
className | string | Additional classes |
RadioGroupField
Group of radio buttons for single selection from multiple options.
<RadioGroupField
name="plan"
label="Select Plan"
description="We'll never share your message."
tooltip="Used for account notifications"
>
<Label htmlFor="plan-free" orientation="horizontal">
<RadioGroupItem value="free" id="plan-free" />
Free
</Label>
<Label htmlFor="plan-pro" orientation="horizontal">
<RadioGroupItem value="pro" id="plan-pro" />
Pro ($9/month)
</Label>
</RadioGroupField>| Prop | Type | Description |
|---|---|---|
name | string | Form field name (simple API) |
field | StringFieldApi | Field instance (advanced API) |
label | React.ReactNode | Field label |
description | React.ReactNode | Helper text under the label |
tooltip | React.ReactNode | Inline info icon content |
children | React.ReactNode | RadioGroupItem children |
className | string | Additional classes |
size | "sm" | "md" | "lg" | Radio group and field chrome size |
SelectField
Dropdown selection from multiple options.
const currencyItems = [
{ label: "USD", value: "usd" },
{ label: "EUR", value: "eur" },
];
<SelectField
items={currencyItems}
name="currency"
label="Currency"
labelSize="sm"
>
<SelectTrigger size="sm">
<SelectValue placeholder="Select..." />
</SelectTrigger>
<SelectContent>
{currencyItems.map((item) => (
<SelectItem key={item.value} value={item.value}>
{item.label}
</SelectItem>
))}
</SelectContent>
</SelectField>| Prop | Type | Description |
|---|---|---|
name | string | Form field name (simple API) |
field | StringFieldApi | Field instance (advanced API) |
label | React.ReactNode | Field label |
description | React.ReactNode | Helper text under the label |
tooltip | React.ReactNode | Inline info icon content |
labelSize | "sm" | "md" | "lg" | Form label, description, and message size |
items | { label: ReactNode, value: string }[] | Label map forwarded to Select; pass it when using the default SelectValue display |
children | React.ReactNode | Custom SelectTrigger/Value/Content/Items; control size lives on SelectTrigger |
className | string | Additional classes for the wrapper |
DateInputField
Segmented date input bound to form state.
<DateInputField name="dob" label="Date of birth" />| Prop | Type | Description |
|---|---|---|
name | string | Form field name (simple API) |
field | FieldApi<Date|string|null> | Field instance (advanced API) |
label | React.ReactNode | Field label |
description | React.ReactNode | Helper text under the label |
tooltip | React.ReactNode | Inline info icon content |
size | "sm" | "md" | "lg" | Date input and field chrome size |
locale | string | Override the segmented input locale (defaults to 'en-AU') |
className | string | Additional classes for the wrapper |
PhoneField
Phone number input powered by the PhoneInput primitive (with country picker, search and flags). Stores values in canonical E.164 format. Defaults to AU for national input and supports international entry via leading +.
<PhoneField name="phone" label="Phone" description="We'll never share your message." tooltip="Used for account notifications" />
// Set a different default country (still allows + for international)
<PhoneField name="phone" label="Phone" defaultCountry="NZ" />Note
- Includes a country selector combobox with flags and search;
defaultCountrysets the initial country. - Stores values in E.164 (canonical). With AU as default, entering 04xx… is saved as +61 4xx…; a leading + always accepts international.
- Built-in validation runs on blur using the phone library; an "Invalid phone number" message is shown until the number is valid, and cleared when empty/valid. Errors render like other fields via the form chrome.
- You can still add extra schema rules (e.g., AU-only mobiles) if needed.
| Prop | Type | Description |
|---|---|---|
name | string | Form field name (simple API) |
field | StringFieldApi | Field instance (advanced API) |
label | React.ReactNode | Field label |
description | React.ReactNode | Helper text under the label |
tooltip | React.ReactNode | Inline info icon content |
size | "sm" | "md" | "lg" | Phone input and field chrome size |
className | string | Additional classes for the wrapper |
placeholder | string | Placeholder for the phone input |
disabled | boolean | Disable the input |
readOnly | boolean | Make the input read-only |
defaultCountry | string | ISO 3166-1 alpha-2 country code used for national input (default: AU) |
TagInputField
Multi-value input for managing tags (chips). Wraps the TagInput primitive and binds it to form state.
// Tag objects (default)
<TagInputField name="topicObjects" label="Topic Objects" description="We'll never share your message." tooltip="Used for account notifications" />
// String[] values (maps to Tag[] internally)
<TagInputField name="topics" label="Topics" asStrings />
// You can pass TagInput props too (e.g., Excel paste, ignore commas)
<TagInputField
name="skills"
label="Skills"
enableExcelPaste
// Allow commas inside tags (typing + paste)
enableCommaDelimiter={false}
options={[{ id: "ts", label: "TypeScript" }, { id: "react", label: "React" }]}
asStrings
/>| Prop | Type | Description |
|---|---|---|
name | string | Form field name (simple API) |
field | TagsFieldApi | StringsFieldApi | Field instance (advanced API) |
label | React.ReactNode | Field label |
description | React.ReactNode | Helper text under the label |
tooltip | React.ReactNode | Inline info icon content |
size | "sm" | "md" | "lg" | Tag input and field chrome size |
options | { id: string; label: string }[] | Predefined selectable tags |
placeholder | string | Placeholder for the input |
className | string | Additional classes for the wrapper |
allowDuplicates | boolean | Allow duplicate tag labels (default: false) |
enableExcelPaste | boolean | Split pasted CSV/TSV/newlines into tags (default: true) |
enableCommaDelimiter | boolean | Comma key creates a tag (default: true) |
pasteDelimiters | string[] | Delimiters used when splitting pasted text |
asStrings | boolean | Bind to string[] instead of Tag[] |
When provided, these sync the TagInputField’s tags to a string[] URL parameter via TanStack Router search params.
| Prop | Type | Default | Description |
|---|---|---|---|
paramName | string | — | URL parameter name to sync. Enables URL state management. |
onUrlValueChange | (value: string[]|null) => void | — | Callback when URL parameter value changes. |
paramClearOnDefault | boolean | true | Remove URL param when value equals default. |
paramThrottle | number | — | Throttle URL updates in milliseconds. |
paramDebounce | number | — | Debounce URL updates in milliseconds. |
SliderField
Range slider for numeric values.
<SliderField
name="volume"
label="Volume"
description="We'll never share your message."
tooltip="Used for account notifications"
valueLabel={true}
min={0}
max={100}
step={10}
/>| Prop | Type | Description |
|---|---|---|
name | string | Form field name (simple API) |
field | NumberFieldApi | Field instance (advanced API) |
label | React.ReactNode | Field label |
description | React.ReactNode | Helper text under the label |
tooltip | React.ReactNode | Inline info icon content |
valueLabel | boolean | React.ReactNode | ((props: {value: string}) => ReactNode) | Show current value |
min | number | Minimum value |
max | number | Maximum value |
step | number | Step increment |
AutocompleteField
Text input with real-time suggestions and filtering. Wraps the Autocomplete primitive and binds it to form state.
const locations = [
{ id: "1", label: "New York" },
{ id: "2", label: "London" },
{ id: "3", label: "Tokyo" },
];
<AutocompleteField
name="location"
label="Location"
description="Select your preferred location"
tooltip="Where you want to work"
items={locations}
itemToString={(loc) => loc.label}
itemToKey={(loc) => loc.id}
placeholder="Search locations..."
emptyMessage="No locations found"
/>;
// Simple string array
const tags = ["React", "TypeScript", "Next.js"];
<AutocompleteField
name="tag"
label="Tag"
items={tags}
itemToString={(tag) => tag}
placeholder="Search tags..."
/>;| Prop | Type | Description |
|---|---|---|
name | string | Form field name (simple API) |
field | StringFieldApi | Field instance (advanced API) |
label | React.ReactNode | Field label |
description | React.ReactNode | Helper text under the label |
tooltip | React.ReactNode | Inline info icon content |
size | "sm" | "md" | "lg" | Autocomplete input and field chrome size |
items | T[] | Array of items to display. Required |
itemToString | (item: T) => string | Convert item to display string. Required |
itemToKey | (item: T) => string | Get unique key for each item (defaults to itemToString) |
placeholder | string | Placeholder text |
emptyMessage | string | Message shown when no items match (default: "No results found.") |
disabled | boolean | Disable the autocomplete |
required | boolean | Mark the field as required (adds aria-required) |
readOnly | boolean | Make the autocomplete read-only |
autoFocus | boolean | Auto-focus the input on mount |
compact | boolean | Hide label, description, and error messages |
className | string | Additional classes for the wrapper |
Note: This field also accepts all props from the underlying Autocomplete primitive (e.g., autoHighlight, filter, open, onOpenChange). See the Autocomplete documentation for full details.
Compact Mode
Use compact for dense layouts like data grids where you want just the input without chrome:
// Standard mode - shows label, description, errors
<InputField name="email" label="Email" description="Your work email" />
// Compact mode - input only, no chrome
<InputField name="email" compact />Compact mode is primarily used internally by the FormBuilder.Bulk grid
component for inline editing.
Dual Prop API
All field components accept either:
name: Automatically binds to form context (recommended for most use cases)field: Direct field API control (for advanced scenarios)
| Prop API | Use Case | Example |
|---|---|---|
name | Standard fields, clean syntax | <InputField name="email" label="Email" /> |
field | Custom logic, validation state access | <form.Field name="email"> {(field) => <InputField field={field} />} </form.Field> |