# Form **Category**: react **URL**: https://www.heroui.com/docs/react/components/form **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/form.mdx > Wrapper component for form validation and submission handling *** ## Import ```tsx import { Form } from '@heroui/react'; ``` ### Usage ```tsx "use client"; import {Check} from "@gravity-ui/icons"; import {Button, Description, FieldError, Form, Input, Label, TextField} from "@heroui/react"; export function Basic() { const onSubmit = (e: React.FormEvent) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record = {}; // Convert FormData to plain object formData.forEach((value, key) => { data[key] = value.toString(); }); alert(`Form submitted with: ${JSON.stringify(data, null, 2)}`); }; return (

{ if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(value)) { return "Please enter a valid email address"; } return null; }} > Email { if (value.length < 8) { return "Password must be at least 8 characters"; } if (!/[A-Z]/.test(value)) { return "Password must contain at least one uppercase letter"; } if (!/[0-9]/.test(value)) { return "Password must contain at least one number"; } return null; }} > Password Must be at least 8 characters with 1 uppercase and 1 number

); } ``` ### Anatomy Import all parts and piece them together. ```tsx import {Form, Button} from '@heroui/react'; export default () => (

{/* Form fields go here */}

); } ``` ## Related Components - **Button**: Allows a user to perform an action - **Fieldset**: Group related form controls with legends - **TextField**: Composition-friendly fields with labels and validation ## Styling ### Passing Tailwind CSS classes ```tsx import {Form, TextField, Label, Input, FieldError, Button} from '@heroui/react'; function CustomForm() { return ( ); } ``` ## API Reference ### Form Props 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) => 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) => void` | - | Handler called when the form is reset. | | `onSubmit` | `(event: FormEvent) => 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` | - | 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) { 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. ### Accessibility Forms are accessible by default when using React Aria components. Key features include: - Native `