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

import { Form } from "@zayne-labs/ui-react/ui/form";
import { useForm } from "react-hook-form";

Component Parts

Form.Root · component

Root form element with context provider

Form.Field · component

Field wrapper with label, input, and error associations

Form.FieldWithController · component

Field with built-in Controller for complex inputs

Form.FieldBoundController · component

Controller bound to parent Field context

Form.FieldContext · component

Context consumer for field metadata

Form.Label · component

Accessible label element

Form.Input · component

Input field with automatic registration

Form.TextArea · component

Multi-line text input

Form.Select · component

Select dropdown input

Form.InputGroup · component

Container for input with left/right items

Form.InputLeftItem · component

Left-side addon for InputGroup

Form.InputRightItem · component

Right-side addon for InputGroup

Form.Description · component

Helper text for the field

Form.ErrorMessage · component

Error message display

Form.Submit · component

Form submit button

Form.Watch · component

Watch form values with render props

Form.StateSubscribe · component

Subscribe to form state changes

Form.Root

Root form element that provides form context to all child components.

Props

form · UseFormReturn<TFieldValues, unknown, TTransformedValues> · required

React Hook Form instance from useForm()

children · React.ReactNode · required

Child components

withEyeIcon · boolean | EyeIconObject

Configure password visibility toggle

• true - Use default eye icon
• false - Disable eye icon
• Object with custom icons:
  { open: ReactNode; closed: ReactNode } |
  { renderIcon: (props: { isPasswordVisible: boolean }) => ReactNode }
  

className · string

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

name · FieldPath<TFieldValues> · required

Field name matching the form schema

control · Control<TFieldValues, unknown, TTransformedValues>

Form control (auto-resolved from context if not provided)

withWrapper · boolean · default: true

Whether to render a wrapper div

• true - Render wrapper with default classes
• false - Only provide context without wrapper

className · string

CSS class names when withWrapper is true. Default includes flex flex-col gap-2

children · React.ReactNode · required

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

name · FieldPath<TFieldValues> · required

Field name matching the form schema

control · Control<TFieldValues, unknown, TTransformedValues>

Form control (auto-resolved from context if not provided)

render · function · required

Render function receiving field props

({ field, fieldState, formState }) => React.ReactElement

rules · RegisterOptions

Validation rules

defaultValue · any

Default field value

shouldUnregister · boolean

Whether to unregister the field on unmount

disabled · boolean

Disable the field

Form.FieldBoundController

Controller that automatically uses the parent Field’s name from context.

Props

render · function · required

Render function receiving field props

({ field, fieldState, formState }) => React.ReactElement

rules · RegisterOptions

Validation rules

defaultValue · any

Default field value

shouldUnregister · boolean

Whether to unregister on unmount

disabled · boolean

Disable the field

Form.FieldContext

Access field context values (name, IDs) via render props.

Props

children · function

Render function receiving field context

(context: {
  name: string;
  formItemId: string;
  formDescriptionId: string;
  formMessageId: string;
}) => React.ReactNode

render · function

Alternative to children

Form.Label

Accessible label element automatically associated with the input.

Props

htmlFor · string

Custom ID for the associated input (auto-resolved from context if not provided)

className · string

CSS class names

children · React.ReactNode

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

type · React.HTMLInputTypeAttribute · default: "text"

Input type (text, email, password, etc.)

rules · RegisterOptions

Validation rules

{
  required: "This field is required",
  minLength: { value: 3, message: "Min 3 characters" },
  pattern: { value: /^[A-Z]/, message: "Must start with uppercase" },
}

className · string

CSS class names

classNames · object

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

withEyeIcon · boolean | EyeIconObject

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

rules · RegisterOptions

Validation rules

className · string

CSS class names

classNames · object

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

rules · RegisterOptions

Validation rules

className · string

CSS class names

classNames · object

Class names for select parts

• base?: string - Select element classes
• error?: string - Error state classes

children · React.ReactNode

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

className · string

CSS class names. Default includes flex items-center justify-between gap-2

children · React.ReactNode · required

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

as · React.ElementType · default: "span"

The element type to render as

className · string

CSS class names. Default includes inline-flex items-center justify-center

children · React.ReactNode

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

as · React.ElementType · default: "span"

The element type to render as

className · string

CSS class names. Default includes inline-flex items-center justify-center

children · React.ReactNode

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

className · string

CSS class names. Default includes text-[12px]

children · React.ReactNode

Description content

Form.ErrorMessage

Display validation error messages.

Props

errorField · FieldPath<TFieldValues> | string

Field name to show errors for (auto-resolved from context if not provided)

type · 'regular' | 'root' · default: "regular"

Error type

• regular - Field-specific errors
• root - Form-level errors

className · string

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

fieldName · FieldPath<TFieldValues> | string · required

Field name to show errors for

type · 'regular' | 'root' · default: "regular"

Error type

control · Control<TFieldValues>

Form control

renderItem · function · required

Custom render function for each error

(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

classNames · object

Class names for error parts

• container?: string - Error list container
• errorMessage?: string - Individual error message
• errorMessageAnimation?: string - Shake animation class (default: animate-shake)

disableErrorAnimation · boolean · default: false

Disable shake animation on error

disableScrollToErrorField · boolean · default: false

Disable auto-scroll to error field

Form.Submit

Form submit button.

Props

as · React.ElementType · default: "button"

The element type to render as

asChild · boolean

Merge props with immediate child element

type · 'submit' | 'button' | 'reset' · default: "submit"

Button type

className · string

CSS class names

children · React.ReactNode

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

name · FieldPath<TFieldValues> | FieldPath<TFieldValues>[]

Field name(s) to watch (auto-resolved from context if not provided)

control · Control<TFieldValues>

Form control

defaultValue · any

Default value when field is undefined

disabled · boolean

Disable watching

exact · boolean

Enable exact match for field names

children · function · required

Render function receiving watched value(s)

(value: TFieldValue) => React.ReactNode

render · function

Alternative to children

Form.StateSubscribe

Subscribe to form state changes (errors, isDirty, isSubmitting, etc.).

Props

name · FieldPath<TFieldValues> | FieldPath<TFieldValues>[]

Field name(s) to subscribe to

control · Control<TFieldValues>

Form control

disabled · boolean

Disable subscription

exact · boolean

Enable exact match for field names

children · function · required

Render function receiving form state

(formState: UseFormStateReturn<TFieldValues>) => React.ReactNode

render · function

Alternative to children

Types

FieldValues

type FieldValues = Record<string, any>;

FieldState

type FieldState = {
  isDisabled?: boolean;
  isInvalid?: boolean;
  errors?: UseFormStateReturn<FieldValues>["errors"];
};

FieldContextValue

type FieldContextValue = {
  name: string;
  formItemId: string;
  formDescriptionId: string;
  formMessageId: string;
};

FormRootContext

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.

import { useFormMethodsContext } from "@zayne-labs/ui-react/ui/form";

function CustomComponent() {
  const { control, handleSubmit, reset } = useFormMethodsContext();
  
  return <button onClick={() => reset()}>Reset</button>;
}

useFormFieldContext

Access the current field context.

import { useFormFieldContext } from "@zayne-labs/ui-react/ui/form";

function CustomComponent() {
  const { name, formItemId } = useFormFieldContext();
  
  return <div>Field: {name}</div>;
}

useFormRootContext

Access the form root context (from React Hook Form).

import { useFormRootContext } from "@zayne-labs/ui-react/ui/form";

function CustomComponent() {
  const formContext = useFormRootContext();
  
  return <div>{formContext.formState.isSubmitting ? "Submitting..." : "Ready"}</div>;
}