> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zayne-labs/ui/llms.txt
> Use this file to discover all available pages before exploring further.
# Form
> API reference for the Form component
A comprehensive form component built on React Hook Form with validation, field state management, and accessibility features.
## Import
```tsx theme={null}
import { Form } from "@zayne-labs/ui-react/ui/form";
import { useForm } from "react-hook-form";
```
## Component Parts
Root form element with context provider
Field wrapper with label, input, and error associations
Field with built-in Controller for complex inputs
Controller bound to parent Field context
Context consumer for field metadata
Accessible label element
Input field with automatic registration
Multi-line text input
Select dropdown input
Container for input with left/right items
Left-side addon for InputGroup
Right-side addon for InputGroup
Helper text for the field
Error message display
Form submit button
Watch form values with render props
Subscribe to form state changes
## Form.Root
Root form element that provides form context to all child components.
### Props
React Hook Form instance from `useForm()`
Child components
Configure password visibility toggle
* `true` - Use default eye icon
* `false` - Disable eye icon
* Object with custom icons:
```tsx theme={null}
{ open: ReactNode; closed: ReactNode } |
{ renderIcon: (props: { isPasswordVisible: boolean }) => ReactNode }
```
CSS class names for the form element. Default includes `flex flex-col`
### Data Attributes
* `data-scope="form"`
* `data-part="root"`
* `data-slot="form-root"`
## Form.Field
Field wrapper that creates context for label, input, description, and error associations.
### Props
Field name matching the form schema
Form control (auto-resolved from context if not provided)
Whether to render a wrapper div
* `true` - Render wrapper with default classes
* `false` - Only provide context without wrapper
CSS class names when `withWrapper` is true. Default includes `flex flex-col gap-2`
Field content
### Data Attributes (when withWrapper is true)
* `data-scope="form"`
* `data-part="field"`
* `data-slot="form-field"`
* `data-disabled` - Present when field is disabled
* `data-invalid` - Present when field has errors
## Form.FieldWithController
Field with built-in Controller for complex/controlled inputs.
### Props
Field name matching the form schema
Form control (auto-resolved from context if not provided)
Render function receiving field props
```tsx theme={null}
({ field, fieldState, formState }) => React.ReactElement
```
Validation rules
Default field value
Whether to unregister the field on unmount
Disable the field
## Form.FieldBoundController
Controller that automatically uses the parent Field's name from context.
### Props
Render function receiving field props
```tsx theme={null}
({ field, fieldState, formState }) => React.ReactElement
```
Validation rules
Default field value
Whether to unregister on unmount
Disable the field
## Form.FieldContext
Access field context values (name, IDs) via render props.
### Props
Render function receiving field context
```tsx theme={null}
(context: {
name: string;
formItemId: string;
formDescriptionId: string;
formMessageId: string;
}) => React.ReactNode
```
Alternative to children
## Form.Label
Accessible label element automatically associated with the input.
### Props
Custom ID for the associated input (auto-resolved from context if not provided)
CSS class names
Label content
### Data Attributes
* `data-scope="form"`
* `data-part="label"`
* `data-slot="form-label"`
* `data-disabled` - Present when field is disabled
* `data-invalid` - Present when field has errors
## Form.Input
Input field with automatic registration and validation.
### Props
Input type (text, email, password, etc.)
Validation rules
```tsx theme={null}
{
required: "This field is required",
minLength: { value: 3, message: "Min 3 characters" },
pattern: { value: /^[A-Z]/, message: "Must start with uppercase" },
}
```
CSS class names
Class names for input parts
* `input?: string` - Input element classes
* `inputGroup?: string` - Input group wrapper classes (for password inputs)
* `eyeIcon?: string` - Password toggle icon classes
* `error?: string` - Error state classes
Password visibility toggle configuration (overrides Form.Root setting)
### Data Attributes
* `data-scope="form"`
* `data-part="input"`
* `data-slot="form-input"`
* `data-disabled` - Present when disabled
* `data-invalid` - Present when field has errors
## Form.TextArea
Multi-line text input field.
### Props
Validation rules
CSS class names
Class names for textarea parts
* `base?: string` - Textarea element classes
* `error?: string` - Error state classes
### Data Attributes
* `data-scope="form"`
* `data-part="textarea"`
* `data-slot="form-textarea"`
* `data-disabled` - Present when disabled
* `data-invalid` - Present when field has errors
## Form.Select
Select dropdown input.
### Props
Validation rules
CSS class names
Class names for select parts
* `base?: string` - Select element classes
* `error?: string` - Error state classes
Option elements
### Data Attributes
* `data-scope="form"`
* `data-part="select"`
* `data-slot="form-select"`
* `data-disabled` - Present when disabled
* `data-invalid` - Present when field has errors
## Form.InputGroup
Container for input with left and/or right addons.
### Props
CSS class names. Default includes `flex items-center justify-between gap-2`
Input element and left/right items
### Data Attributes
* `data-scope="form"`
* `data-part="input-group"`
* `data-slot="form-input-group"`
* `data-disabled` - Present when field is disabled
* `data-invalid` - Present when field has errors
## Form.InputLeftItem
Left-side addon for InputGroup.
### Props
The element type to render as
CSS class names. Default includes `inline-flex items-center justify-center`
Addon content (icon, text, etc.)
### Data Attributes
* `data-scope="form"`
* `data-part="left-item"`
* `data-slot="form-left-item"`
## Form.InputRightItem
Right-side addon for InputGroup.
### Props
The element type to render as
CSS class names. Default includes `inline-flex items-center justify-center`
Addon content (icon, text, etc.)
### Data Attributes
* `data-scope="form"`
* `data-part="right-item"`
* `data-slot="form-right-item"`
## Form.Description
Helper text providing additional context for the field.
### Props
CSS class names. Default includes `text-[12px]`
Description content
## Form.ErrorMessage
Display validation error messages.
### Props
Field name to show errors for (auto-resolved from context if not provided)
Error type
* `regular` - Field-specific errors
* `root` - Form-level errors
CSS class names for error messages. Default includes `text-[13px] text-zu-destructive`
### Data Attributes
* `data-scope="form"`
* `data-part="error-message"`
* `data-slot="form-error-message"`
* `data-index` - Message index for multiple errors
## Form.ErrorMessagePrimitive
Low-level error message component with full customization.
### Props
Field name to show errors for
Error type
Form control
Custom render function for each error
```tsx theme={null}
(context: {
props: {
id: string;
className: string;
'data-scope': 'form';
'data-part': 'error-message';
'data-index': number;
};
state: {
errorMessage: string;
errorMessageArray: string[];
index: number;
};
}) => React.ReactNode
```
Class names for error parts
* `container?: string` - Error list container
* `errorMessage?: string` - Individual error message
* `errorMessageAnimation?: string` - Shake animation class (default: `animate-shake`)
Disable shake animation on error
Disable auto-scroll to error field
## Form.Submit
Form submit button.
### Props
The element type to render as
Merge props with immediate child element
Button type
CSS class names
Button content
### Data Attributes
* `data-scope="form"`
* `data-part="submit"`
* `data-slot="form-submit"`
## Form.Watch
Watch form values and render based on changes.
### Props
Field name(s) to watch (auto-resolved from context if not provided)
Form control
Default value when field is undefined
Disable watching
Enable exact match for field names
Render function receiving watched value(s)
```tsx theme={null}
(value: TFieldValue) => React.ReactNode
```
Alternative to children
## Form.StateSubscribe
Subscribe to form state changes (errors, isDirty, isSubmitting, etc.).
### Props
Field name(s) to subscribe to
Form control
Disable subscription
Enable exact match for field names
Render function receiving form state
```tsx theme={null}
(formState: UseFormStateReturn) => React.ReactNode
```
Alternative to children
## Types
### FieldValues
```tsx theme={null}
type FieldValues = Record;
```
### FieldState
```tsx theme={null}
type FieldState = {
isDisabled?: boolean;
isInvalid?: boolean;
errors?: UseFormStateReturn["errors"];
};
```
### FieldContextValue
```tsx theme={null}
type FieldContextValue = {
name: string;
formItemId: string;
formDescriptionId: string;
formMessageId: string;
};
```
### FormRootContext
```tsx theme={null}
type FormRootContext = {
withEyeIcon: boolean | EyeIconObject | undefined;
};
type EyeIconObject =
| { open: React.ReactNode; closed: React.ReactNode }
| { renderIcon: (props: { isPasswordVisible: boolean }) => React.ReactNode };
```
## Hooks
### useFormMethodsContext
Access the form methods from React Hook Form.
```tsx theme={null}
import { useFormMethodsContext } from "@zayne-labs/ui-react/ui/form";
function CustomComponent() {
const { control, handleSubmit, reset } = useFormMethodsContext();
return ;
}
```
### useFormFieldContext
Access the current field context.
```tsx theme={null}
import { useFormFieldContext } from "@zayne-labs/ui-react/ui/form";
function CustomComponent() {
const { name, formItemId } = useFormFieldContext();
return
Field: {name}
;
}
```
### useFormRootContext
Access the form root context (from React Hook Form).
```tsx theme={null}
import { useFormRootContext } from "@zayne-labs/ui-react/ui/form";
function CustomComponent() {
const formContext = useFormRootContext();
return