//
A form field element.
bun add xiod-ui1import {2 Field,3 FieldControl,4 FieldDescription,5 FieldError,6 FieldItem,7 FieldLabel,8 FieldValidity9} from "xiod-ui/field";1<Field>2 <FieldDescription />3 <FieldLabel />4 <FieldItem />5 <FieldControl />6 <FieldError />7 <FieldValidity />8</Field>| Prop | Type | Default | Description |
|---|---|---|---|
disabled | boolean| undefined | false | Whether the component should ignore user interaction. Takes precedence over the `disabled` prop on the `<Field.Control>` component. |
name | string| undefined | - | Identifies the field when a form is submitted. Takes precedence over the `name` prop on the `<Field.Control>` component. |
validate | ((value: unknown, formValues: Record<string, any>) => string| void| string[]| Promise<string| void| string[]| null>| null)| undefined | - | A function for custom validation. Return a string or an array of strings with the error message(s) if the value is invalid. Returning nothing, `null`, an empty string, or an empty array means the value is valid. Asynchronous functions are supported, but they do not prevent form submission when using `validationMode="onSubmit"`. |
validationMode | FormValidationMode| undefined | 'onSubmit' | Determines when the field should be validated. This takes precedence over the `validationMode` prop on `<Form>`. - `onSubmit`: triggers validation when the form is submitted, and re-validates on change after submission. - `onBlur`: triggers validation when the control loses focus. - `onChange`: triggers validation on every change to the control value. |
validationDebounceTime | number| undefined | 0 | How long to wait between `validate` callbacks if `validationMode="onChange"` is used. Specified in milliseconds. |
invalid | boolean| undefined | - | Whether the field is invalid. Useful when the field state is controlled by an external library. |
dirty | boolean| undefined | - | Whether the field's value has been changed from its initial value. Useful when the field state is controlled by an external library. |
touched | boolean| undefined | - | Whether the field has been touched. Useful when the field state is controlled by an external library. |
actionsRef | RefObject<FieldRootActions| null>| undefined | - | A ref to imperative actions. - `validate`: Validates the field when called. |
className | string| ((state: FieldRootState) => string| undefined)| undefined | - | CSS class applied to the element, or a function that returns a class based on the component's state. |
render | ReactElement<unknown, string| JSXElementConstructor<any>>| ComponentRenderFn<HTMLProps, FieldRootState>| undefined | - | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
style | CSSProperties| ((state: FieldRootState) => CSSProperties| undefined)| undefined | - | Style applied to the element, or a function that returns a style object based on the component's state. |
| Prop | Type | Default | Description |
|---|---|---|---|
style | CSSProperties| ((state: FieldControlState) => CSSProperties| undefined)| undefined | - | Style applied to the element, or a function that returns a style object based on the component's state. |
className | string| ((state: FieldControlState) => string| undefined)| undefined | - | CSS class applied to the element, or a function that returns a class based on the component's state. |
defaultValue | string| number| readonly string[]| undefined | - | |
render | ReactElement<unknown, string| JSXElementConstructor<any>>| ComponentRenderFn<HTMLProps, FieldControlState>| undefined | - | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
onValueChange | ((value: string, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element| undefined; }) => void)| undefined | - | Callback fired when the `value` changes. Use when controlled. |
| Prop | Type | Default | Description |
|---|---|---|---|
className | string| ((state: FieldDescriptionState) => string| undefined)| undefined | - | CSS class applied to the element, or a function that returns a class based on the component's state. |
render | ReactElement<unknown, string| JSXElementConstructor<any>>| ComponentRenderFn<HTMLProps, FieldDescriptionState>| undefined | - | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
style | CSSProperties| ((state: FieldDescriptionState) => CSSProperties| undefined)| undefined | - | Style applied to the element, or a function that returns a style object based on the component's state. |
| Prop | Type | Default | Description |
|---|---|---|---|
match | boolean| keyof ValidityState| undefined | - | Determines whether to show the error message according to the field's [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState). Specifying `true` will always show the error message, and lets external libraries control the visibility. |
className | string| ((state: FieldErrorState) => string| undefined)| undefined | - | CSS class applied to the element, or a function that returns a class based on the component's state. |
render | ReactElement<unknown, string| JSXElementConstructor<any>>| ComponentRenderFn<HTMLProps, FieldErrorState>| undefined | - | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
style | CSSProperties| ((state: FieldErrorState) => CSSProperties| undefined)| undefined | - | Style applied to the element, or a function that returns a style object based on the component's state. |
| Prop | Type | Default | Description |
|---|---|---|---|
disabled | boolean| undefined | false | Whether the wrapped control should ignore user interaction. The `disabled` prop on `<Field.Root>` takes precedence over this. |
className | string| ((state: FieldItemState) => string| undefined)| undefined | - | CSS class applied to the element, or a function that returns a class based on the component's state. |
render | ReactElement<unknown, string| JSXElementConstructor<any>>| ComponentRenderFn<HTMLProps, FieldItemState>| undefined | - | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
style | CSSProperties| ((state: FieldItemState) => CSSProperties| undefined)| undefined | - | Style applied to the element, or a function that returns a style object based on the component's state. |
| Prop | Type | Default | Description |
|---|---|---|---|
nativeLabel | boolean| undefined | true | Whether the component renders a native `<label>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a label (for example, `<div>`). This is useful to avoid inheriting label behaviors on `<button>` controls (such as `<Select.Trigger>` and `<Combobox.Trigger>`), including avoiding `:hover` on the button when hovering the label, and preventing clicks on the label from firing on the button. |
className | string| ((state: FieldLabelState) => string| undefined)| undefined | - | CSS class applied to the element, or a function that returns a class based on the component's state. |
render | ReactElement<unknown, string| JSXElementConstructor<any>>| ComponentRenderFn<HTMLProps, FieldLabelState>| undefined | - | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
style | CSSProperties| ((state: FieldLabelState) => CSSProperties| undefined)| undefined | - | Style applied to the element, or a function that returns a style object based on the component's state. |
| Prop | Type | Default | Description |
|---|---|---|---|
childrenReq | (state: FieldValidityState) => ReactNode | - | A function that accepts the field validity state as an argument. ```jsx <Field.Validity> {(validity) => { return <div>...</div> }} </Field.Validity> ``` |