---
title: Form
description: Wrapper component for form validation and submission handling
links:
  source: form/form.tsx
  rac: https://react-spectrum.adobe.com/react-aria/Form.html
---

## Usage

```tsx
import { Form } from '@heroui/react';
```

<ComponentPreview name="form-basic" />

## Anatomy

```tsx
import {Form, Button} from '@heroui/react';

export default () => (
  <Form>
    {/* Form fields go here */}
    <Button type="submit"/>
    <Button type="reset"/>
  </Form>
)
```

## Examples

### Render Function

<ComponentPreview
  name="form-render-function"
/>

## Customization

### Tailwind CSS

<ComponentPreview name="form-custom-styles" />

### Global CSS

To customize form layout and spacing, use the `className` prop on `<Form>` or add a project-level class with the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

`Form` renders a native `<form>` element and focuses on validation and submission. It does not include dedicated BEM classes in `@heroui/styles`—apply container styles from global CSS, and use field components for control-level customization.

```css
@layer components {
  .form-layout {
    @apply flex flex-col gap-4 rounded-xl border border-border bg-surface p-4 shadow-sm;
  }
}
```

```tsx
<Form className="form-layout" onSubmit={handleSubmit}>
  {/* TextField, Input, Button, etc. */}
</Form>
```

For grouped fields with shared layout, use [Fieldset](./fieldset) and target `.fieldset`, `.fieldset__legend`, and related classes. For individual controls, see **Global CSS** on [TextField](./text-field), [Input](./input), [Label](./label), and [FieldError](./field-error).

## Styling Reference

HeroUI follows the [BEM](https://getbem.com/) methodology for components that ship styles in `@heroui/styles`.

`Form` renders a native `<form>` element without dedicated BEM classes. Apply layout, spacing, and surface styles through `className`. Field appearance and validation states come from child components such as `TextField`, `Input`, `Label`, `Description`, and `FieldError`. For structured multi-field layouts, compose with [Fieldset](./fieldset).

## API Reference

### Form

The Form component is a wrapper around React Aria's Form primitive that provides form validation and submission handling capabilities.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `action` | `string \| FormHTMLAttributes['action']` | - | The URL to submit the form data to. |
| `className` | `string` | - | Tailwind CSS classes applied to the form element. |
| `children` | `React.ReactNode` | - | Form content (fields, buttons, etc.). |
| `encType` | `'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'` | - | The encoding type for form data submission. |
| `method` | `'get' \| 'post'` | - | The HTTP method to use when submitting the form. |
| `onInvalid` | `(event: FormEvent<HTMLFormElement>) => void` | - | Handler called when the form validation fails. By default, the first invalid field will be focused. Use `preventDefault()` to customize focus behavior. |
| `onReset` | `(event: FormEvent<HTMLFormElement>) => void` | - | Handler called when the form is reset. |
| `onSubmit` | `(event: FormEvent<HTMLFormElement>) => void` | - | Handler called when the form is submitted. |
| `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | - | Where to display the response after submitting the form. |
| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML validation or ARIA validation. 'native' blocks form submission, 'aria' displays errors in realtime. |
| `validationErrors` | `ValidationErrors` | - | Server-side validation errors mapped by field name. Displayed immediately and cleared when user modifies the field. |
| `aria-label` | `string` | - | Accessibility label for the form. |
| `aria-labelledby` | `string` | - | ID of element that labels the form. Creates a form landmark when provided. |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | Overrides the default DOM element with a custom render function.|

### Form Validation

The Form component integrates with React Aria's validation system, allowing you to:

- Use built-in HTML5 validation attributes (`required`, `minLength`, `pattern`, etc.)
- Provide custom validation functions on TextField components
- Display validation errors with FieldError components
- Handle form submission with proper validation
- Provide server-side validation errors via `validationErrors` prop

#### Validation Behavior

The `validationBehavior` prop controls how validation is displayed:

- **`native`** (default): Uses native HTML validation, blocks form submission on errors
- **`aria`**: Uses ARIA attributes for validation, displays errors in realtime as user types, doesn't block submission

This behavior can be set at the form level or overridden at individual field level.

### Form Submission

Forms can be submitted in several ways:

- **Traditional submission**: Set the `action` prop to submit to a URL
- **JavaScript handling**: Use the `onSubmit` handler to process form data
- **FormData API**: Access form data using the FormData API in your submit handler

Example with FormData:

```tsx
function handleSubmit(e: FormEvent<HTMLFormElement>) {
  e.preventDefault();
  const formData = new FormData(e.currentTarget);
  const data = Object.fromEntries(formData);
  console.log('Form data:', data);
}
```

### Integration with Form Fields

The Form component works seamlessly with HeroUI's form field components:

- **TextField**: For text inputs with labels and validation
- **Checkbox**: For boolean selections
- **RadioGroup**: For single selection from multiple options
- **Switch**: For toggle controls
- **Button**: For form submission and reset actions

All field components automatically integrate with the Form's validation and submission behavior when placed inside it.

### Advanced Usage

For more advanced use cases including:
- Custom validation context
- Form context providers
- Integration with third-party libraries
- Custom focus management on validation errors

Please refer to the [React Aria Form documentation](https://react-spectrum.adobe.com/react-aria/Form.html).

## Accessibility

Forms are accessible by default when using React Aria components. Key features include:

- Native `<form>` element semantics
- Form landmark creation with `aria-label` or `aria-labelledby`
- Automatic focus management on validation errors
- ARIA validation attributes when using `validationBehavior="aria"`

## Related Showcases

<RelatedShowcases component="Form" />

## Related Components

<RelatedComponents component="form" />
