チェックボックスグループ
CheckboxGroupを使用すると、ユーザーは選択肢のリストから1つ以上の項目を選択できます。
インストール
npx nextui-cli@latest add checkbox
上記のコマンドは個別インストール専用です。もし、 @nextui-org/react がグローバルにインストール済みであれば、このステップはスキップできます。
インポート
NextUIは、チェックボックス関連のコンポーネントを2つエクスポートします。
- CheckboxGroup: ルートコンポーネントで、ラベルとラッパーをラップします。
- Checkbox: チェックボックスコンポーネント。
使い方
無効
水平
制御された
value および onValueChange プロパティを使用して、チェックボックスの入力値を制御できます。
無効な状態
スロット
- base: チェックボックスグループのルートラッパーで、ラベルとラッパーをラップします。
- wrapper: チェックボックスグループのラッパーで、すべてのチェックボックスをラップします。
- label: チェックボックスグループのラベルで、ラッパーの前に配置されます。
- description: チェックボックスグループの説明。
- errorMessage: チェックボックスグループのエラーメッセージ。
カスタムスタイル
コンポーネントスロットにカスタムの Tailwind CSS クラスを渡すことで、CheckboxGroup コンポーネントをカスタマイズできます。
カスタム実装
チェックボックスをさらにカスタマイズする必要がある場合は、useCheckboxGroup フックを使用して独自の実装を作成できます。
注: 上記のスタイルを実装するために、Tailwind Variants を使用しました。同じ結果を得るために、clsx のような他のライブラリも使用できます。
API
チェックボックスグループのプロパティ
| 属性 | 型 | 説明 | デフォルト |
|---|---|---|---|
| children | ReactNode[] | ReactNode[] | チェックボックスの項目。 | - |
| orientation | vertical | horizontal | チェックボックスグループの項目が整列する軸。 | vertical |
| color | default | primary | secondary | success | warning | danger | チェックボックスの色。 | primary |
| size | xs | sm | md | lg | xl | チェックボックスのサイズ。 | md |
| radius | none | base | xs | sm | md | lg | xl | full | チェックボックスの角丸。 | md |
| name | string | HTMLフォームを送信する際に使用される CheckboxGroup の名前。 | - |
| label | string | CheckboxGroup のラベル。 | - |
| value | string[] | 現在選択されている値。（制御された状態）。 | - |
| lineThrough | boolean | チェックボックスのラベルに打ち消し線を引くかどうか。 | false |
| defaultValue | string[] | デフォルトで選択されている値。（非制御状態）。 | - |
| isInvalid | boolean | チェックボックスグループが無効かどうか。 | false |
| validationState | valid | invalid | 入力が「有効」または「無効」の視覚的なスタイルを表示するかどうか。（非推奨）代わりに isInvalid を使用してください。 | - |
| description | ReactNode | チェックボックスグループの説明。 | - |
| errorMessage | ReactNode | ((v: ValidationResult) => ReactNode) | チェックボックスグループのエラーメッセージ。 | - |
| validate | (value: string[]) => ValidationError ｜ true ｜ null ｜ undefined | コミット時（例：フォーカスが外れたとき）に入力値を検証し、無効な値に対してエラーメッセージを返します。 validationBehavior が native に設定されている場合、検証エラーはフォーム送信時に表示されます。リアルタイム検証には、isInvalid プロパティを使用してください。 | - |
| validationBehavior | native | aria | 値が欠落しているか無効な場合にフォーム送信を防ぐためにネイティブ HTML フォーム検証を使用するか、ARIA を介してフィールドを必須または無効としてマークするかどうか。 | aria |
| isDisabled | boolean | チェックボックスグループが無効になっているかどうか。 | false |
| isRequired | boolean | フォーム送信前にユーザーがチェックボックスへの入力を必須とするかどうか。 | false |
| isReadOnly | boolean | チェックボックスを選択できるが、ユーザーが変更できないかどうか。 | - |
| disableAnimation | boolean | アニメーションを無効にするかどうか。 | false |
| classNames | Record<"base"｜ "wrapper"｜ "label", string> | チェックボックスグループのスロットにカスタムクラス名を設定できます。 | - |
チェックボックスグループのイベント
| 属性 | 型 | 説明 |
|---|---|---|
| onChange | (value: string[]) => void | 値が変更されたときに呼び出されるハンドラー。 |
