--- title: Form description: "`Form` is a component used to group multiple form elements." links: - style: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/form/form.style.ts - source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/form - storybook: https://yamada-ui.github.io/yamada-ui?path=/story/components-form--basic --- ```tsx interface Data { email: string name: string password: string } const { formState: { errors }, handleSubmit, register, } = useForm() const onSubmit: SubmitHandler = (data) => console.log("submit:", data) return ( value?.message)} invalid={extractObject(errors, (value) => !!value)} required={{ name: true, email: true }} onSubmit={handleSubmit(onSubmit)} > Create an account Create an account to get started. Submit ) ``` ## Usage ```tsx import { Form } from "@yamada-ui/react" ``` ```tsx import { Form } from "@/components/ui" ``` ```tsx import { Form } from "@workspaces/ui" ``` ```tsx ``` ### Use props ```tsx const { formState: { errors }, handleSubmit, register, } = useForm() const onSubmit: SubmitHandler = (data) => console.log("submit:", data) return ( value?.message)} invalid={extractObject(errors, (value) => !!value)} required={{ name: true, email: true }} onSubmit={handleSubmit(onSubmit)} > ) ``` ### Change Variant ```tsx const { formState: { errors }, handleSubmit, register, } = useForm() const onSubmit: SubmitHandler = (data) => console.log("submit:", data) return ( {(variant, key) => ( value?.message)} invalid={extractObject(errors, (value) => !!value)} required={{ name: true, email: true }} onSubmit={handleSubmit(onSubmit)} > )} ) ``` ### Change Size ```tsx const { formState: { errors }, handleSubmit, register, } = useForm() const onSubmit: SubmitHandler = (data) => console.log("submit:", data) return ( {(size, key) => ( value?.message)} invalid={extractObject(errors, (value) => !!value)} required={{ name: true, email: true }} onSubmit={handleSubmit(onSubmit)} > )} ) ``` ### Displaying a Helper Message To display a helper message, set a `{[key: string]: ReactNode}` to `helperMessage`. ```tsx const { formState: { errors }, handleSubmit, register, } = useForm() const onSubmit: SubmitHandler = (data) => console.log("submit:", data) return ( value?.message)} invalid={extractObject(errors, (value) => !!value)} required={{ name: true, email: true }} onSubmit={handleSubmit(onSubmit)} > ) ``` ### Displaying an Error Message To display an error message, set a `{[key: string]: ReactNode}` to `errorMessage`. ```tsx const { formState: { errors }, handleSubmit, register, } = useForm() const onSubmit: SubmitHandler = (data) => console.log("submit:", data) return ( value?.message)} invalid={extractObject(errors, (value) => !!value)} required={{ name: true, email: true }} onSubmit={handleSubmit(onSubmit)} > ) ``` ### Required To make it required, set `required` to `{[key: string]: boolean}`. ```tsx const { formState: { errors }, handleSubmit, register, } = useForm() const onSubmit: SubmitHandler = (data) => console.log("submit:", data) return ( value?.message)} invalid={extractObject(errors, (value) => !!value)} required={{ name: true, email: true }} onSubmit={handleSubmit(onSubmit)} > ) ``` ### Disable To disable, set `disabled` to `{[key: string]: boolean}`. ```tsx const { formState: { errors }, handleSubmit, register, } = useForm() const onSubmit: SubmitHandler = (data) => console.log("submit:", data) return ( value?.message)} invalid={extractObject(errors, (value) => !!value)} required={{ name: true, email: true }} disabled={{ password: true }} onSubmit={handleSubmit(onSubmit)} > ) ``` ### Read-Only To make it read-only, set `readOnly` to `{[key: string]: boolean}`. ```tsx const { formState: { errors }, handleSubmit, register, } = useForm() const onSubmit: SubmitHandler = (data) => console.log("submit:", data) return ( value?.message)} invalid={extractObject(errors, (value) => !!value)} required={{ name: true, email: true }} readOnly={{ password: true }} submitButton="Submit" title="Create an account" onSubmit={handleSubmit(onSubmit)} > ) ``` ### Customize Required Indicator To customize the required indicator, set `requiredIndicator` to `ReactNode`. ```tsx const { formState: { errors }, handleSubmit, register, } = useForm() const onSubmit: SubmitHandler = (data) => console.log("submit:", data) return ( value?.message)} invalid={extractObject(errors, (value) => !!value)} required={{ name: true, email: true }} requiredIndicator={ required } onSubmit={handleSubmit(onSubmit)} > ) ``` ### Use Optional Indicator To use an optional indicator, set a `ReactNode` to `optionalIndicator`. ```tsx const { formState: { errors }, handleSubmit, register, } = useForm() const onSubmit: SubmitHandler = (data) => console.log("submit:", data) return ( value?.message)} invalid={extractObject(errors, (value) => !!value)} required={{ name: true, email: true }} requiredIndicator={ required } optionalIndicator={ optional } onSubmit={handleSubmit(onSubmit)} > ) ``` ## Uses Components & Hooks ## Used By Components & Hooks ## Props ### Form.Root | Prop | Default | Type | Description | | ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | `as` | - | `As` | The HTML element to render. | | `asChild` | - | `boolean` | Merges its props onto its immediate child. | | `css` | - | `CSSObject \| CSSObject[]` | The CSS object. | | `colorScheme` | - | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables. | | `size` | `"md"` | `"lg" \| "md" \| "sm"` | The size of the component. | | `variant` | `"plain"` | `"elevated" \| "outline" \| "panel" \| "plain"` | The variant of the component. | | `bodyProps` | - | `FormBodyProps` | Props the body component. | | `description` | - | `ReactNode` | The form description to use. | | `descriptionProps` | - | `FormDescriptionProps` | Props the description component. | | `disabled` | - | `boolean \| { [key: string]: boolean \| undefined }` | An object managing the disabled state of each field. | | `errorMessage` | - | `{ [key: string]: ReactNode }` | An object managing the error message of each field. | | `footerProps` | - | `FormFooterProps` | Props the footer component. | | `headerProps` | - | `FormHeaderProps` | Props the header component. | | `helperMessage` | - | `{ [key: string]: ReactNode }` | An object managing the helper message of each field. | | `invalid` | - | `boolean \| { [key: string]: boolean \| undefined }` | An object managing the invalid state of each field. | | `optionalIndicator` | - | `ReactNode` | The optional indicator to use for each field. | | `readOnly` | - | `boolean \| { [key: string]: boolean \| undefined }` | An object managing the read only state of each field. | | `replace` | - | `boolean \| { [key: string]: boolean \| undefined }` | An object managing the replace state of each field. | | `required` | - | `boolean \| { [key: string]: boolean \| undefined }` | An object managing the required state of each field. | | `requiredIndicator` | - | `ReactNode` | The required indicator to use for each field. | | `submitButton` | - | `ReactNode` | The submit button to use. | | `submitButtonProps` | - | `FormSubmitButtonProps` | Props the submit button component. | | `title` | - | `ReactNode` | The form title to use. | | `titleProps` | - | `FormTitleProps` | Props the title component. | ### Form.Body | Prop | Default | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `as` | - | `As` | The HTML element to render. | | `asChild` | - | `boolean` | Merges its props onto its immediate child. | | `css` | - | `CSSObject \| CSSObject[]` | The CSS object. | | `colorScheme` | - | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables. | ### Form.Description | Prop | Default | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `as` | - | `As` | The HTML element to render. | | `asChild` | - | `boolean` | Merges its props onto its immediate child. | | `css` | - | `CSSObject \| CSSObject[]` | The CSS object. | | `colorScheme` | - | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables. | ### Form.Footer | Prop | Default | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `as` | - | `As` | The HTML element to render. | | `asChild` | - | `boolean` | Merges its props onto its immediate child. | | `css` | - | `CSSObject \| CSSObject[]` | The CSS object. | | `colorScheme` | - | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables. | ### Form.Group | Prop | Default | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `as` | - | `As` | The HTML element to render. | | `asChild` | - | `boolean` | Merges its props onto its immediate child. | | `css` | - | `CSSObject \| CSSObject[]` | The CSS object. | | `colorScheme` | - | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables. | ### Form.Header | Prop | Default | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `as` | - | `As` | The HTML element to render. | | `asChild` | - | `boolean` | Merges its props onto its immediate child. | | `css` | - | `CSSObject \| CSSObject[]` | The CSS object. | | `colorScheme` | - | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables. | ### Form.SubmitButton | Prop | Default | Type | Description | | ------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `as` | - | `As` | The HTML element to render. | | `asChild` | - | `boolean` | Merges its props onto its immediate child. | | `css` | - | `CSSObject \| CSSObject[]` | The CSS object. | | `colorScheme` | - | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables. | | `size` | - | `"2xl" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"` | The size of the component. | | `variant` | - | `"ghost" \| "outline" \| "solid" \| "subtle" \| "surface" ...` | The variant of the component. | | `active` | `false` | `boolean` | If `true`, the button is represented as active. | | `disabled` | `false` | `boolean` | If `true`, the button is disabled. | | `disableRipple` | `false` | `boolean` | If `true`, disable ripple effects when pressing a element. | | `endIcon` | - | `ReactNode` | The icon to display at the end side of the button. | | `iconProps` | - | `ButtonIconProps` | The props of the icon element. | | `loading` | `false` | `boolean` | If `true`, the loading state of the button is represented. | | `loadingIcon` | `"oval"` | `Loading.Scheme \| ReactNode` | The icon to display when the button is loading. | | `loadingMessage` | - | `ReactNode` | The message to display when the button is loading. | | `loadingPlacement` | `"start"` | `"end" \| "start"` | The placement of the loading indicator. Accepts `start` or `end`. | | `loadingProps` | - | `ButtonLoadingProps` | The props of the loading icon element. | | `startIcon` | - | `ReactNode` | The icon to display at the start side of the button. | | `type` | `"button"` | `HTMLProps<"button">["type"]` | The type of button. Accepts `button`, `reset`, or `submit`. | ### Form.Title | Prop | Default | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `as` | - | `As` | The HTML element to render. | | `asChild` | - | `boolean` | Merges its props onto its immediate child. | | `css` | - | `CSSObject \| CSSObject[]` | The CSS object. | | `colorScheme` | - | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables. |