Form

Form is a component used to group multiple form elements.

interface Data {
  email: string
  name: string
  password: string
}

const {
  formState: { errors },
  handleSubmit,
  register,
} = useForm<Data>()

const onSubmit: SubmitHandler<Data> = (data) => console.log("submit:", data)

return (
  <Form.Root
    helperMessage={{
      password: "If not set, a password will be automatically generated.",
    }}
    errorMessage={extractObject(errors, (value) => value?.message)}
    invalid={extractObject(errors, (value) => !!value)}
    required={{ name: true, email: true }}
    onSubmit={handleSubmit(onSubmit)}
  >
    <Form.Header>
      <Form.Title>Create an account</Form.Title>
      <Form.Description>Create an account to get started.</Form.Description>
    </Form.Header>

    <Form.Body>
      <Form.Group>
        <Field.Root name="name" label="Name">
          <Input
            placeholder="Hirotomo Yamada"
            {...register("name", {
              required: { message: "Name is required", value: true },
            })}
          />
        </Field.Root>

        <Field.Root name="email" label="Email address">
          <Input
            placeholder="hirotomo@yamada-ui.com"
            {...register("email", {
              required: { message: "Email is required", value: true },
            })}
          />
        </Field.Root>

        <Field.Root name="password" label="Password">
          <PasswordInput placeholder="password" {...register("password")} />
        </Field.Root>
      </Form.Group>
    </Form.Body>

    <Form.Footer>
      <Form.SubmitButton>Submit</Form.SubmitButton>
    </Form.Footer>
  </Form.Root>
)

Usage

import { Form } from "@yamada-ui/react"

import { Form } from "@/components/ui"

import { Form } from "@workspaces/ui"

<Form.Root>
  <Form.Header>
    <Form.Title />
    <Form.Description />
  </Form.Header>
  <Form.Body>
    <Form.Group />
  </Form.Body>
  <Form.Footer>
    <Form.SubmitButton />
  </Form.Footer>
</Form.Root>

Use props

const {
  formState: { errors },
  handleSubmit,
  register,
} = useForm<Data>()

const onSubmit: SubmitHandler<Data> = (data) => console.log("submit:", data)

return (
  <Form.Root
    title="Create an account"
    description="Create an account to get started."
    submitButton="Submit"
    helperMessage={{
      password: "If not set, a password will be automatically generated.",
    }}
    errorMessage={extractObject(errors, (value) => value?.message)}
    invalid={extractObject(errors, (value) => !!value)}
    required={{ name: true, email: true }}
    onSubmit={handleSubmit(onSubmit)}
  >
    <Form.Group>
      <Field.Root name="name" label="Name">
        <Input
          placeholder="Hirotomo Yamada"
          {...register("name", {
            required: { message: "Name is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root name="email" label="Email address">
        <Input
          placeholder="hirotomo@yamada-ui.com"
          {...register("email", {
            required: { message: "Email is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root name="password" label="Password">
        <PasswordInput placeholder="password" {...register("password")} />
      </Field.Root>
    </Form.Group>
  </Form.Root>
)

Change Variant

const {
  formState: { errors },
  handleSubmit,
  register,
} = useForm<Data>()

const onSubmit: SubmitHandler<Data> = (data) => console.log("submit:", data)

return (
  <VStack>
    <For each={["plain", "elevated", "outline", "panel"]}>
      {(variant, key) => (
        <Form.Root
          key={key}
          variant={variant}
          title="Create an account"
          description="Create an account to get started."
          submitButton="Submit"
          helperMessage={{
            password: "If not set, a password will be automatically generated.",
          }}
          errorMessage={extractObject(errors, (value) => value?.message)}
          invalid={extractObject(errors, (value) => !!value)}
          required={{ name: true, email: true }}
          onSubmit={handleSubmit(onSubmit)}
        >
          <Fieldset.Root legend="Personal information">
            <Field.Root name="name" label="Name">
              <Input
                placeholder="Hirotomo Yamada"
                {...register("name", {
                  required: { message: "Name is required", value: true },
                })}
              />
            </Field.Root>

            <Field.Root name="password" label="Password">
              <PasswordInput placeholder="password" {...register("password")} />
            </Field.Root>
          </Fieldset.Root>
        </Form.Root>
      )}
    </For>
  </VStack>
)

Change Size

const {
  formState: { errors },
  handleSubmit,
  register,
} = useForm<Data>()

const onSubmit: SubmitHandler<Data> = (data) => console.log("submit:", data)

return (
  <VStack>
    <For each={["sm", "md", "lg"]}>
      {(size, key) => (
        <Form.Root
          key={key}
          size={size}
          variant="panel"
          title="Create an account"
          description="Create an account to get started."
          submitButton="Submit"
          helperMessage={{
            password: "If not set, a password will be automatically generated.",
          }}
          errorMessage={extractObject(errors, (value) => value?.message)}
          invalid={extractObject(errors, (value) => !!value)}
          required={{ name: true, email: true }}
          onSubmit={handleSubmit(onSubmit)}
        >
          <Fieldset.Root legend="Personal information">
            <Field.Root name="name" label="Name">
              <Input
                placeholder="Hirotomo Yamada"
                {...register("name", {
                  required: { message: "Name is required", value: true },
                })}
              />
            </Field.Root>

            <Field.Root name="password" label="Password">
              <PasswordInput placeholder="password" {...register("password")} />
            </Field.Root>
          </Fieldset.Root>
        </Form.Root>
      )}
    </For>
  </VStack>
)

Displaying a Helper Message

To display a helper message, set a {[key: string]: ReactNode} to helperMessage.

const {
  formState: { errors },
  handleSubmit,
  register,
} = useForm<Data>()

const onSubmit: SubmitHandler<Data> = (data) => console.log("submit:", data)

return (
  <Form.Root
    title="Create an account"
    description="Create an account to get started."
    submitButton="Submit"
    helperMessage={{
      password: "If not set, a password will be automatically generated.",
    }}
    errorMessage={extractObject(errors, (value) => value?.message)}
    invalid={extractObject(errors, (value) => !!value)}
    required={{ name: true, email: true }}
    onSubmit={handleSubmit(onSubmit)}
  >
    <Form.Group>
      <Field.Root name="name" label="Name">
        <Input
          placeholder="Hirotomo Yamada"
          {...register("name", {
            required: { message: "Name is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root name="email" label="Email address">
        <Input
          placeholder="hirotomo@yamada-ui.com"
          {...register("email", {
            required: { message: "Email is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root name="password" label="Password">
        <PasswordInput placeholder="password" {...register("password")} />
      </Field.Root>
    </Form.Group>
  </Form.Root>
)

Displaying an Error Message

To display an error message, set a {[key: string]: ReactNode} to errorMessage.

const {
  formState: { errors },
  handleSubmit,
  register,
} = useForm<Data>()

const onSubmit: SubmitHandler<Data> = (data) => console.log("submit:", data)

return (
  <Form.Root
    title="Create an account"
    description="Create an account to get started."
    submitButton="Submit"
    errorMessage={extractObject(errors, (value) => value?.message)}
    invalid={extractObject(errors, (value) => !!value)}
    required={{ name: true, email: true }}
    onSubmit={handleSubmit(onSubmit)}
  >
    <Form.Group>
      <Field.Root name="name" label="Name">
        <Input
          placeholder="Hirotomo Yamada"
          {...register("name", {
            required: { message: "Name is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root name="email" label="Email address">
        <Input
          placeholder="hirotomo@yamada-ui.com"
          {...register("email", {
            required: { message: "Email is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root
        name="password"
        helperMessage="If not set, a password will be automatically generated."
        label="Password"
      >
        <PasswordInput placeholder="password" {...register("password")} />
      </Field.Root>
    </Form.Group>
  </Form.Root>
)

Required

To make it required, set required to {[key: string]: boolean}.

const {
  formState: { errors },
  handleSubmit,
  register,
} = useForm<Data>()

const onSubmit: SubmitHandler<Data> = (data) => console.log("submit:", data)

return (
  <Form.Root
    title="Create an account"
    description="Create an account to get started."
    submitButton="Submit"
    errorMessage={extractObject(errors, (value) => value?.message)}
    invalid={extractObject(errors, (value) => !!value)}
    required={{ name: true, email: true }}
    onSubmit={handleSubmit(onSubmit)}
  >
    <Form.Group>
      <Field.Root name="name" label="Name">
        <Input
          placeholder="Hirotomo Yamada"
          {...register("name", {
            required: { message: "Name is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root name="email" label="Email address">
        <Input
          placeholder="hirotomo@yamada-ui.com"
          {...register("email", {
            required: { message: "Email is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root
        name="password"
        helperMessage="If not set, a password will be automatically generated."
        label="Password"
      >
        <PasswordInput placeholder="password" {...register("password")} />
      </Field.Root>
    </Form.Group>
  </Form.Root>
)

Disable

To disable, set disabled to {[key: string]: boolean}.

const {
  formState: { errors },
  handleSubmit,
  register,
} = useForm<Data>()

const onSubmit: SubmitHandler<Data> = (data) => console.log("submit:", data)

return (
  <Form.Root
    title="Create an account"
    description="Create an account to get started."
    submitButton="Submit"
    errorMessage={extractObject(errors, (value) => value?.message)}
    invalid={extractObject(errors, (value) => !!value)}
    required={{ name: true, email: true }}
    disabled={{ password: true }}
    onSubmit={handleSubmit(onSubmit)}
  >
    <Form.Group>
      <Field.Root name="name" label="Name">
        <Input
          placeholder="Hirotomo Yamada"
          {...register("name", {
            required: { message: "Name is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root name="email" label="Email address">
        <Input
          placeholder="hirotomo@yamada-ui.com"
          {...register("email", {
            required: { message: "Email is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root
        name="password"
        helperMessage="If not set, a password will be automatically generated."
        label="Password"
      >
        <PasswordInput placeholder="password" {...register("password")} />
      </Field.Root>
    </Form.Group>
  </Form.Root>
)

Read-Only

To make it read-only, set readOnly to {[key: string]: boolean}.

const {
  formState: { errors },
  handleSubmit,
  register,
} = useForm<Data>()

const onSubmit: SubmitHandler<Data> = (data) => console.log("submit:", data)

return (
  <Form.Root
    description="Create an account to get started."
    errorMessage={extractObject(errors, (value) => value?.message)}
    invalid={extractObject(errors, (value) => !!value)}
    required={{ name: true, email: true }}
    readOnly={{ password: true }}
    submitButton="Submit"
    title="Create an account"
    onSubmit={handleSubmit(onSubmit)}
  >
    <Form.Group>
      <Field.Root name="name" label="Name">
        <Input
          placeholder="Hirotomo Yamada"
          {...register("name", {
            required: { message: "Name is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root name="email" label="Email address">
        <Input
          placeholder="hirotomo@yamada-ui.com"
          {...register("email", {
            required: { message: "Email is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root
        name="password"
        helperMessage="If not set, a password will be automatically generated."
        label="Password"
      >
        <PasswordInput placeholder="password" {...register("password")} />
      </Field.Root>
    </Form.Group>
  </Form.Root>
)

Customize Required Indicator

To customize the required indicator, set requiredIndicator to ReactNode.

const {
  formState: { errors },
  handleSubmit,
  register,
} = useForm<Data>()

const onSubmit: SubmitHandler<Data> = (data) => console.log("submit:", data)

return (
  <Form.Root
    title="Create an account"
    description="Create an account to get started."
    submitButton="Submit"
    errorMessage={extractObject(errors, (value) => value?.message)}
    invalid={extractObject(errors, (value) => !!value)}
    required={{ name: true, email: true }}
    requiredIndicator={
      <Tag colorScheme="red" size="sm">
        required
      </Tag>
    }
    onSubmit={handleSubmit(onSubmit)}
  >
    <Form.Group>
      <Field.Root name="name" label="Name">
        <Input
          placeholder="Hirotomo Yamada"
          {...register("name", {
            required: { message: "Name is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root name="email" label="Email address">
        <Input
          placeholder="hirotomo@yamada-ui.com"
          {...register("email", {
            required: { message: "Email is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root
        name="password"
        helperMessage="If not set, a password will be automatically generated."
        label="Password"
      >
        <PasswordInput placeholder="password" {...register("password")} />
      </Field.Root>
    </Form.Group>
  </Form.Root>
)

Use Optional Indicator

To use an optional indicator, set a ReactNode to optionalIndicator.

const {
  formState: { errors },
  handleSubmit,
  register,
} = useForm<Data>()

const onSubmit: SubmitHandler<Data> = (data) => console.log("submit:", data)

return (
  <Form.Root
    title="Create an account"
    description="Create an account to get started."
    submitButton="Submit"
    errorMessage={extractObject(errors, (value) => value?.message)}
    invalid={extractObject(errors, (value) => !!value)}
    required={{ name: true, email: true }}
    requiredIndicator={
      <Tag colorScheme="red" size="sm">
        required
      </Tag>
    }
    optionalIndicator={
      <Tag colorScheme="mono" size="sm">
        optional
      </Tag>
    }
    onSubmit={handleSubmit(onSubmit)}
  >
    <Form.Group>
      <Field.Root name="name" label="Name">
        <Input
          placeholder="Hirotomo Yamada"
          {...register("name", {
            required: { message: "Name is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root name="email" label="Email address">
        <Input
          placeholder="hirotomo@yamada-ui.com"
          {...register("email", {
            required: { message: "Email is required", value: true },
          })}
        />
      </Field.Root>

      <Field.Root
        name="password"
        helperMessage="If not set, a password will be automatically generated."
        label="Password"
      >
        <PasswordInput placeholder="password" {...register("password")} />
      </Field.Root>
    </Form.Group>
  </Form.Root>
)

Accessibility

ARIA Roles and Attributes

Component	Roles and Attributes	Usage
`Form.Root`	`id`	Used to associate with `Form.SubmitButton`.
	`aria-labelledby`	Sets the `id` of the associated `Form.Title` and `Form.Description`.
`Form.Title`	`id`	Used to associate with `Form.Root` and `Form.Description`.
`Form.Description`	`id`	Used to associate with `Form.Root`.
	`aria-describedby`	Sets the `id` of the associated `Form.Title`.
`Form.SubmitButton`	`form`	Sets the `id` of the associated `Form.Root`.

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.

Similar Components

Field is a component used to group form elements with label, helper message, error message, etc.

Fieldset is a component used to group elements such as legends, helper messages, and error messages in a fieldset element.

Bleed is a component used to extend elements beyond the boundaries of a container.

Box is the most abstract component on which all other components are built. By default, it renders a div element.

Center is a component that aligns the child elements in the center within the component.

Container is a component used as a general division element. By default, it renders the section element.

Flex is a component that sets flex to Box. Also, convenient style shorthand is available.

Float is a component used to fix elements to the edges of a container.

Uses Components & Hooks

Button is an interactive component that allows users to perform actions such as submitting forms and toggling modals.

Used By Components & Hooks

Field is a component used to group form elements with label, helper message, error message, etc.

Fieldset is a component used to group elements such as legends, helper messages, and error messages in a fieldset element.