Form

A composable form component with field validation, labels, and actions for building accessible forms

Installation

Install the Form component component using the nocta-ui CLI:

npx nocta-ui add form

Import the component:

import {
  Form,
  FormField,
  FormLabel,
  FormControl,
  FormDescription,
  FormMessage,
  FormActions,
  FormInput,
  FormSubmit,
} from '@/components/ui/form';

Examples

The Form component follows a composable architecture where you build forms by combining smaller components together.

Form Architecture

The Form component is built with a composable architecture:

Form: The main form container (Ariakit Form)
FormField: Wraps individual form fields and provides context
FormLabel: Accessible labels with required field indicators (Ariakit Label)
FormControl: Wrapper that connects inputs to the field context
FormDescription: Helper text for additional guidance
FormMessage: Error, success, and warning messages (uses Ariakit FormError when no explicit message provided)
FormActions: Container for form action buttons
FormInput: Input bound to the current field name (Ariakit FormInput)
FormSubmit: Submit button integrated with Ariakit (Ariakit FormSubmit)

Error Handling

Handle validation in two ways:

Pass an error prop to FormField and place <FormMessage /> to display it.
Or use an Ariakit form store with validate/setError and place <FormMessage type="error" /> to read errors from the store.

Complex Forms

Build complex forms with multiple field types, layouts, and validation.

Form Actions

The FormActions component supports different alignments for form buttons.

Message Types

Form messages support different types for various validation states.

Api Reference

Prop	Type	Default	Description
`children`	`React.ReactNode`	—	Form content
`className`	`string`	`''`	Additional CSS classes
`onSubmit`	`(event: React.FormEvent) => void`	—	Form submit handler
`store`	`FormStore`	`useFormStore({})`	Optional Ariakit form store

FormField

Prop	Type	Default	Description
`children`	`React.ReactNode`	—	Field content
`name`	`string`	—	Field name identifier
`error`	`string`	—	Error message to display
`description`	`string`	—	Description text
`className`	`string`	`''`	Additional CSS classes

FormLabel

Prop	Type	Default	Description
`children`	`React.ReactNode`	—	Label content
`className`	`string`	`''`	Additional CSS classes
`required`	`boolean`	`false`	Show required indicator

FormMessage

Prop	Type	Default	Description
`children`	`React.ReactNode`	—	Message content
`className`	`string`	`''`	Additional CSS classes
`type`	`'error' \| 'success' \| 'warning'`	`'error'`	Message type

FormActions

Prop	Type	Default	Description
`children`	`React.ReactNode`	—	Action buttons
`className`	`string`	`''`	Additional CSS classes
`align`	`'left' \| 'center' \| 'right'`	`'right'`	Button alignment

FormInput

Prop	Type	Default	Description
`className`	`string`	`''`	Additional CSS classes
`...inputProps`	`InputHTMLAttributes<HTMLInputElement>`	—	Native input props forwarded to Ariakit FormInput

FormSubmit

Prop	Type	Default	Description
`children`	`React.ReactNode`	—	Button content
`className`	`string`	`''`	Additional CSS classes
`...buttonProps`	`ButtonHTMLAttributes<HTMLButtonElement>`	—	Native button props forwarded to Ariakit FormSubmit

The Form components also accept all standard HTML attributes for their respective elements.

Form

On this page