Checkbox

Checkboxは、ユーザーが複数の選択肢の中から複数の値を選択するために使用されるコンポーネントです。

デスティニーアイランド

<Checkbox>デスティニーアイランド</Checkbox>

使い方

import { Checkbox, CheckboxGroup } from "@yamada-ui/react"

import { Checkbox, CheckboxGroup } from "@/components/ui"

import { Checkbox, CheckboxGroup } from "@workspaces/ui"

<Checkbox />

<CheckboxGroup.Root>
  <CheckboxGroup.Item />
</CheckboxGroup.Root>

グループ化する

ソラリクカイリ

<CheckboxGroup.Root defaultValue={["sora", "riku"]}>
  <CheckboxGroup.Item value="sora">ソラ</CheckboxGroup.Item>
  <CheckboxGroup.Item value="riku">リク</CheckboxGroup.Item>
  <CheckboxGroup.Item value="kairi">カイリ</CheckboxGroup.Item>
</CheckboxGroup.Root>

itemsを使う

ソラリクカイリ

const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "ソラ", value: "sora" },
    { label: "リク", value: "riku" },
    { label: "カイリ", value: "kairi" },
  ],
  [],
)

return <CheckboxGroup.Root items={items} />

バリアントを変更する

const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "Checked", value: "1" },
    { label: "No checked", value: "2" },
  ],
  [],
)

return (
  <VStack>
    <For each={["solid", "subtle", "surface", "outline"]}>
      {(variant) => (
        <CheckboxGroup.Root
          key={variant}
          variant={variant}
          defaultValue={["1"]}
          items={items}
        />
      )}
    </For>
  </VStack>
)

サイズを変更する

const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "Checked", value: "1" },
    { label: "No checked", value: "2" },
  ],
  [],
)

return (
  <VStack>
    <For each={["sm", "md", "lg"]}>
      {(size) => (
        <CheckboxGroup.Root
          key={size}
          size={size}
          defaultValue={["1"]}
          items={items}
        />
      )}
    </For>
  </VStack>
)

デフォルト値を設定する

デフォルト値を設定する場合は、defaultValueに値を設定します。

ソラリクカイリ

const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "ソラ", value: "sora" },
    { label: "リク", value: "riku" },
    { label: "カイリ", value: "kairi" },
  ],
  [],
)

return <CheckboxGroup.Root defaultValue={["sora"]} items={items} />

デフォルトで選択済みにする

デフォルトで選択済みにする場合は、defaultCheckedをtrueに設定します。

デスティニーアイランド

<Checkbox defaultChecked>デスティニーアイランド</Checkbox>

中間状態にする

中間状態にする場合は、indeterminateをtrueに設定します。

デスティニーアイランド

ソラリクカイリ

const [id0, id1, id2] = useIds()
const [values, setValues] = useState([true, false, false])

const allChecked = values.every(Boolean)
const indeterminate = values.some(Boolean) && !allChecked

return (
  <VStack gap="sm">
    <Checkbox
      checked={allChecked}
      indeterminate={indeterminate}
      aria-controls={cx(id0, id1, id2)}
      onChange={(ev) =>
        setValues([ev.target.checked, ev.target.checked, ev.target.checked])
      }
    >
      デスティニーアイランド
    </Checkbox>

    <VStack gap="sm" ms="md">
      <Checkbox
        id={id0}
        checked={values[0]}
        onChange={(ev) =>
          setValues([ev.target.checked, values[1]!, values[2]!])
        }
      >
        ソラ
      </Checkbox>
      <Checkbox
        id={id1}
        checked={values[1]}
        onChange={(ev) =>
          setValues([values[0]!, ev.target.checked, values[2]!])
        }
      >
        リク
      </Checkbox>
      <Checkbox
        id={id2}
        checked={values[2]}
        onChange={(ev) =>
          setValues([values[0]!, values[1]!, ev.target.checked])
        }
      >
        カイリ
      </Checkbox>
    </VStack>
  </VStack>
)

こちらのコードを使用する場合は、"use client"をファイルの上部に追加する必要があります。

選択数を制限する

選択数を制限する場合は、maxに数値を設定します。

ソラリクカイリ

const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "ソラ", value: "sora" },
    { label: "リク", value: "riku" },
    { label: "カイリ", value: "kairi" },
  ],
  [],
)

return <CheckboxGroup.Root items={items} max={2} />

方向を変更する

方向を変更する場合は、orientationに"horizontal"または"vertical"を設定します。デフォルトは"vertical"です。

const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "ソラ", value: "sora" },
    { label: "リク", value: "riku" },
    { label: "カイリ", value: "kairi" },
  ],
  [],
)

return (
  <VStack>
    <For each={["horizontal", "vertical"]}>
      {(orientation) => (
        <CheckboxGroup.Root
          key={orientation}
          orientation={orientation}
          items={items}
        />
      )}
    </For>
  </VStack>
)

形を変更する

形を変更する場合は、shapeに"rounded"または"square"を設定します。デフォルトは"rounded"です。

RoundedSquare

<CheckboxGroup.Root>
  <For each={["rounded", "square"]}>
    {(shape) => (
      <CheckboxGroup.Item key={shape} shape={shape} defaultChecked>
        {toTitleCase(shape)}
      </CheckboxGroup.Item>
    )}
  </For>
</CheckboxGroup.Root>

無効にする

無効にする場合は、disabledをtrueに設定します。

SolidSubtleSurfaceOutline

<CheckboxGroup.Root>
  <For each={["solid", "subtle", "surface", "outline"]}>
    {(variant) => (
      <CheckboxGroup.Item key={variant} variant={variant} disabled>
        {toTitleCase(variant)}
      </CheckboxGroup.Item>
    )}
  </For>
</CheckboxGroup.Root>

読み取り専用にする

読み取り専用にする場合は、readOnlyをtrueに設定します。

SolidSubtleSurfaceOutline

<CheckboxGroup.Root>
  <For each={["solid", "subtle", "surface", "outline"]}>
    {(variant) => (
      <CheckboxGroup.Item
        key={variant}
        variant={variant}
        readOnly
        defaultChecked
      >
        {toTitleCase(variant)}
      </CheckboxGroup.Item>
    )}
  </For>
</CheckboxGroup.Root>

無効な入力にする

無効な入力にする場合は、invalidをtrueに設定します。

SolidSubtleSurfaceOutline

<CheckboxGroup.Root>
  <For each={["solid", "subtle", "surface", "outline"]}>
    {(variant) => (
      <CheckboxGroup.Item key={variant} variant={variant} invalid>
        {toTitleCase(variant)}
      </CheckboxGroup.Item>
    )}
  </For>
</CheckboxGroup.Root>

ボーダーの色を変更する

ボーダーの色を変更する場合は、focusBorderColorまたはerrorBorderColorに値を設定します。

Default Border ColorCustom Border ColorCustom Error Border Color

<CheckboxGroup.Root>
  <CheckboxGroup.Item value="default">Default Border Color</CheckboxGroup.Item>
  <CheckboxGroup.Item focusBorderColor="green.500" value="custom">
    Custom Border Color
  </CheckboxGroup.Item>
  <CheckboxGroup.Item errorBorderColor="orange.500" invalid value="error">
    Custom Error Border Color
  </CheckboxGroup.Item>
</CheckboxGroup.Root>

アイコンをカスタマイズする

アイコンをカスタマイズする場合は、checkedIconにReactNodeを設定します。

ソラリクカイリ

const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "ソラ", value: "sora" },
    { label: "リク", value: "riku" },
    { label: "カイリ", value: "kairi", checkedIcon: <HeartIcon /> },
  ],
  [],
)

return <CheckboxGroup.Root checkedIcon={<KeyIcon />} items={items} />

カスタムコンポーネントを使う

ソラリクカイリ

const { getInputProps, getLabelProps, getRootProps } = useCheckboxGroup({
  defaultValue: ["sora"],
  max: 2,
})

const CustomCheckbox = ({ children, ...rest }) => {
  return (
    <Box
      as="label"
      css={{
        "&:has(input:checked)": {
          bg: "colorScheme.solid",
          borderColor: "colorScheme.solid",
          color: "colorScheme.contrast",
        },
        "&:has(input:disabled)": {
          layerStyle: "disabled",
        },
        alignItems: "center",
        borderWidth: "1px",
        display: "flex",
        h: "10",
        px: "3",
        rounded: "l2",
      }}
      {...getLabelProps()}
    >
      <Box as="input" {...getInputProps(rest)} />
      {children}
    </Box>
  )
}

return (
  <HStack {...getRootProps()}>
    <CustomCheckbox value="sora">ソラ</CustomCheckbox>
    <CustomCheckbox value="riku">リク</CustomCheckbox>
    <CustomCheckbox value="kairi">カイリ</CustomCheckbox>
  </HStack>
)

こちらのコードを使用する場合は、"use client"をファイルの上部に追加する必要があります。

制御する

ソラ

const [checked, { toggle }] = useBoolean(false)

return (
  <Checkbox checked={checked} onChange={toggle}>
    ソラ
  </Checkbox>
)

こちらのコードを使用する場合は、"use client"をファイルの上部に追加する必要があります。

Props

Checkbox

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`	`"solid"`	`"outline" \| "solid" \| "subtle" \| "surface"` The variant of the component.
`checked`	-	`boolean` If `true`, the checkbox will be checked.
`checkedIcon`	-	`ReactNode` The icon to display in the checkbox when it is checked.
`defaultChecked`	`false`	`boolean` If `true`, the checkbox will be initially checked.
`disabled`	`false`	`boolean` If `true`, the field will be disabled.
`errorBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is invalid.
`focusBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is focused.
`id`	-	`string` id assigned to input.
`indeterminate`	`false`	`boolean` If `true`, the checkbox will be indeterminate.
`indeterminateIcon`	-	`ReactNode` The icon to display in the checkbox when it is indeterminate.
`indicatorProps`	-	`CheckboxIndicatorProps` Props for the indicator component.
`inputProps`	-	`HTMLStyledProps<"input">` Props for the input element.
`invalid`	`false`	`boolean` If `true`, the field will be invalid.
`labelProps`	-	`CheckboxLabelProps` Props for the label component.
`name`	-	`string` The name of the input field in a checkbox.
`onBlur`	-	`FocusEventHandler<HTMLInputElement>` The callback invoked when the checkbox is blurred.
`onChange`	-	`ChangeEventHandler<HTMLInputElement>` The callback invoked when the checked state changes.
`onFocus`	-	`FocusEventHandler<HTMLInputElement>` The callback invoked when the checkbox is focused.
`readOnly`	`false`	`boolean` If `true`, the field will be readonly.
`required`	`false`	`boolean` If `true`, the field will be required.
`rootProps`	-	`HTMLStyledProps<"label">` Props for the label element.
`value`	-	`Y` The value of the checkbox.

CheckboxGroup.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`	`"solid"`	`"outline" \| "solid" \| "subtle" \| "surface"` The variant of the component.
`align`	-	`"-moz-initial" \| "anchor-center" \| "baseline" \| "center" \| "end" \| "flex-end" \| "flex-start" \| "inherit" \| "initial" \| "normal" ...` The CSS `align-items` property.
`basis`	-	`"-moz-fit-content" \| "-moz-initial" \| "-moz-max-content" \| "-moz-min-content" \| "-webkit-auto" \| "0.5" \| "1.5" \| "1" \| "1/12" \| "1/2" ...` The CSS `flex-basis` property.
`checkedIcon`	-	`string \| number \| bigint \| boolean \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<...>` The icon to display in the checkbox when it is checked.
`defaultValue`	`[]`	`Y[]` The initial value of the checkbox group.
`direction`	-	`"-moz-initial" \| "column-reverse" \| "column" \| "inherit" \| "initial" \| "revert-layer" \| "revert" \| "row-reverse" \| "row" \| "unset" ...` The CSS `flex-direction` property.
`disabled`	`false`	`boolean` If `true`, the field will be disabled.
`errorBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is invalid.
`focusBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is focused.
`invalid`	`false`	`boolean` If `true`, the field will be invalid.
`items`	`[]`	`CheckboxGroupItem<Y>[]` If provided, generate options based on items.
`justify`	-	`"-moz-initial" \| "center" \| "end" \| "flex-end" \| "flex-start" \| "inherit" \| "initial" \| "left" \| "normal" \| "revert-layer" ...` The CSS `justify-content` property.
`max`	-	`number` The maximum number of checkboxes that can be checked.
`onChange`	-	`(value: Y[]) => void` The callback fired when any children checkbox is checked or unchecked.
`readOnly`	`false`	`boolean` If `true`, the field will be readonly.
`required`	`false`	`boolean` If `true`, the field will be required.
`shrink`	-	`"-moz-initial" \| "inherit" \| "initial" \| "revert-layer" \| "revert" \| "unset" \| AnyString \| number & {} ...` The CSS `flex-shrink` property.
`value`	-	`Y[]` The value of the checkbox group.
`wrap`	-	`"-moz-initial" \| "inherit" \| "initial" \| "nowrap" \| "revert-layer" \| "revert" \| "unset" \| "wrap-reverse" \| "wrap" \| AnyString ...` The CSS `flex-wrap` property.

CheckboxGroup.Item

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`	`"solid"`	`"outline" \| "solid" \| "subtle" \| "surface"` The variant of the component.
`checked`	-	`boolean` If `true`, the checkbox will be checked.
`checkedIcon`	-	`ReactNode` The icon to display in the checkbox when it is checked.
`defaultChecked`	`false`	`boolean` If `true`, the checkbox will be initially checked.
`disabled`	`false`	`boolean` If `true`, the field will be disabled.
`errorBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is invalid.
`focusBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is focused.
`id`	-	`string` id assigned to input.
`indeterminate`	`false`	`boolean` If `true`, the checkbox will be indeterminate.
`indeterminateIcon`	-	`ReactNode` The icon to display in the checkbox when it is indeterminate.
`indicatorProps`	-	`CheckboxIndicatorProps` Props for the indicator component.
`inputProps`	-	`HTMLStyledProps<"input">` Props for the input element.
`invalid`	`false`	`boolean` If `true`, the field will be invalid.
`labelProps`	-	`CheckboxLabelProps` Props for the label component.
`name`	-	`string` The name of the input field in a checkbox.
`onBlur`	-	`FocusEventHandler<HTMLInputElement>` The callback invoked when the checkbox is blurred.
`onChange`	-	`ChangeEventHandler<HTMLInputElement>` The callback invoked when the checked state changes.
`onFocus`	-	`FocusEventHandler<HTMLInputElement>` The callback invoked when the checkbox is focused.
`readOnly`	`false`	`boolean` If `true`, the field will be readonly.
`required`	`false`	`boolean` If `true`, the field will be required.
`rootProps`	-	`HTMLStyledProps<"label">` Props for the label element.
`value`	-	`Y` The value of the checkbox.

アクセシビリティ

Checkboxは、アクセシビリティに関してWAI-ARIA - Checkbox Patternに従います。

Field.Rootを使用しない場合は、CheckboxGroup.Rootにaria-labelまたはaria-labelledbyを設定します。

<CheckboxGroup.Root aria-label="キャラクター">
  <CheckboxGroup.Item value="sora">ソラ</CheckboxGroup.Item>
  <CheckboxGroup.Item value="riku">リク</CheckboxGroup.Item>
  <CheckboxGroup.Item value="kairi">カイリ</CheckboxGroup.Item>
</CheckboxGroup.Root>

<VStack gap="sm">
  <Text as="h3" id="label">
    キャラクター
  </Text>

  <CheckboxGroup.Root aria-labelledby="label">
    <CheckboxGroup.Item value="sora">ソラ</CheckboxGroup.Item>
    <CheckboxGroup.Item value="riku">リク</CheckboxGroup.Item>
    <CheckboxGroup.Item value="kairi">カイリ</CheckboxGroup.Item>
  </CheckboxGroup.Root>
</VStack>

キー	説明	状態
`Space`	フォーカスされたチェックボックスのチェック状態を切り替えます。	-

ARIAロールと属性

要素	ロールと属性	使い方
`div.ui-checkbox__group`	`role="group"`	グループであることを示します。
	`aria-labelledby`	`CheckboxGroup.Root`が`Field.Root`内にあり、`Field.Root`に`label`または`Field.Label`が設定されている場合は、その`id`を設定します。
	`aria-describedby`	`CheckboxGroup.Root`が`Field.Root`内にあり、`Field.Root`に`errorMessage`または`helperMessage`、もしくは`Field.ErrorMessage`または`Field.HelperMessage`が設定されている場合は、その`id`を設定します。
`label.ui-checkbox__root > input`	`aria-checked`	チェックボックスがチェックされている場合は`"true"`を設定し、チェックされていない場合は`"false"`を設定し、`indeterminate`が設定されている場合は`"mixed"`を設定します。
	`aria-describedby`	`Checkbox`が`Field.Root`内にあり、`Field.Root`に`errorMessage`または`helperMessage`、もしくは`Field.ErrorMessage`または`Field.HelperMessage`が設定されている場合は、その`id`を設定します。
	`aria-disabled`	`readOnly`が設定されている場合、またはチェックボックスが未選択でグループの`max`に達した場合に`"true"`を設定します。`disabled`はネイティブの`disabled`属性で表現されます。
	`aria-invalid`	`invalid`が設定されている場合は`"true"`を設定します。
	`aria-required`	`required`が設定されている場合は`"true"`を設定します。
`div.ui-checkbox__indicator`	`aria-hidden`	要素をアクセシビリティツリーから除外します。

類似のコンポーネント

NativeSelectは、ユーザーがオプションのリストから1つの値を選択するために使用されるコンポーネントです。ブラウザ（ユーザーエージェント）によって提供されるネイティブなドロップダウンリストを表示します。

Radioは、ユーザーが複数の選択肢の中から1つの値を選択するために使用されるコンポーネントです。

Ratingは、ユーザーが評価を行うために使用させるコンポーネントです。

SegmentedControlは、ユーザーが複数の選択肢の中から1つを選択するために使用されるコンポーネントです。

Switchは、オンとオフの状態を切り替えるために使用されるコンポーネントです。

CheckboxCardは、ユーザーが複数の選択肢の中から複数の値を選択するために使用されるコンポーネントです。

RadioCardは、ユーザーが複数の選択肢の中から1つの値を選択するために使用されるコンポーネントです。

Toggleは、オンまたはオフの２つの状態を持つコンポーネントです。

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

Groupは、複数の要素をまとめて扱うためのコンポーネントです。

Inputは、ユーザーからのテキスト入力を取得するために使用されるコンポーネントです。

Iconは、プロジェクトに使用できる一般的なアイコンコンポーネントです。

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

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

CheckboxCardは、ユーザーが複数の選択肢の中から複数の値を選択するために使用されるコンポーネントです。

Tableは、列のソートや行の選択やクリックイベント機能を備えたテーブルのコンポーネントです。

Treeは、階層データを展開可能なツリー形式で表示するコンポーネントです。