Form

Formは、複数のフォーム要素をグループ化するためのコンポーネントです。

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>
)

使い方

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>

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>
)

バリアントを変更する

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>
)

サイズを変更する

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>
)

ヘルプメッセージを表示する

ヘルプメッセージを表示する場合は、helperMessageに{[key: string]: 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"
    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>
)

エラーメッセージを表示する

エラーメッセージを表示する場合は、errorMessageに{[key: string]: 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 }}
    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に{[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>
)

無効にする

無効にする場合は、disabledに{[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>
)

読み取り専用にする

読み取り専用にする場合は、readOnlyに{[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>
)

必須インジケーターをカスタマイズする

必須インジケーターをカスタマイズする場合は、requiredIndicatorに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>
)

オプショナルインジケーターを使う

オプショナルインジケーターを使う場合は、optionalIndicatorに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>
    }
    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>
)

アクセシビリティ

ARIAロールと属性

要素	ロールと属性	使い方
`form.ui-form__root`	`id`	`button.ui-form__submit-button`と関連付けるために使用する`id`。
	`aria-labelledby`	関連した`h3.ui-form__title`と`p.ui-form__description`の`id`を設定します。
`h3.ui-form__title`	`id`	`form.ui-form__root`や`p.ui-form__description`と関連付けるために使用する`id`。
`p.ui-form__description`	`id`	`form.ui-form__root`と関連付けるために使用する`id`。
	`aria-describedby`	関連した`h3.ui-form__title`の`id`を設定します。
`button.ui-form__submit-button`	`form`	関連した`form.ui-form__root`の`id`を設定します。

Props

Form.Root

Prop	デフォルト	型 / 説明
`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	デフォルト	型 / 説明
`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	デフォルト	型 / 説明
`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	デフォルト	型 / 説明
`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	デフォルト	型 / 説明
`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	デフォルト	型 / 説明
`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	デフォルト	型 / 説明
`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	デフォルト	型 / 説明
`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.

類似のコンポーネント

Fieldは、フォーム要素に、ラベル、ヘルパーメッセージ、エラーメッセージなどをグループ化するために使用されるコンポーネントです。

Fieldsetは、フィールドセット要素に、レジェンド、ヘルパーメッセージ、エラーメッセージなどをグループ化するために使用されるコンポーネントです。

Bleedは、要素をコンテナの境界から外すために使用されるコンポーネントです。

Boxは、他のすべてのコンポーネントがその上に構築される最も抽象的なコンポーネントです。デフォルトでは、div要素をレンダリングします。

Centerは、コンポーネント内の子要素を中央に配置するコンポーネントです。

Containerは、汎用的な区分要素として使用するコンポーネントです。デフォルトでは、section要素をレンダリングします。

Flexは、Boxにflexを設定したコンポーネントです。また、便利なスタイルのショートハンドが用意されています。

Floatは、要素をコンテナの端に固定するために使用されるコンポーネントです。

使用しているコンポーネント・フック

Buttonは、フォームの送信、モーダルの開閉など、ユーザーが操作できるインタラクティブなコンポーネントです。

使用されているコンポーネント・フック

Fieldは、フォーム要素に、ラベル、ヘルパーメッセージ、エラーメッセージなどをグループ化するために使用されるコンポーネントです。