72Commencer
HextaUI

Checkbox

Une case à cocher dont la coche se dessine, avec des parents indéterminés, des groupes et des libellés qui partagent son survol.

import { Checkbox } from "@/components/ui/checkbox"

export function CheckboxDemo() {
  return (
    <div className="flex flex-col gap-3">
      <label className="flex items-center gap-3 text-sm">
        <Checkbox />
        Email me about product updates
      </label>
      <label className="flex items-center gap-3 text-sm">
        <Checkbox defaultChecked />
        Remember this device
      </label>
      <label className="flex max-w-sm items-start gap-3 text-sm">
        <span className="flex h-5 items-center">
          <Checkbox />
        </span>
        <span className="flex flex-col gap-0.5">
          <span className="leading-5 font-medium">Mentions and replies</span>
          <span className="text-muted-foreground">
            We’ll only notify you about activity on your own posts.
          </span>
        </span>
      </label>
    </div>
  )
}

Installation

pnpm dlx shadcn@latest add https://hextaui.com/r/checkbox.json

Ajoute le composant, les tokens de thème HextaUI et les composants HextaUI dont il dépend.

Utilisation

import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox"
<label className="flex items-center gap-3">
  <Checkbox defaultChecked />
  Remember this device
</label>

Composition

CheckboxGroup
└── Checkbox

Exemples

États

disabled, readOnly, indeterminate et aria-invalid. Une case en lecture seule garde sa valeur et reste focusable, mais ignore les clics et les touches.

import { Checkbox } from "@/components/ui/checkbox"

export function CheckboxStates() {
  return (
    <div className="flex flex-col gap-3 text-sm">
      <label className="flex items-center gap-3">
        <Checkbox disabled />
        Disabled
      </label>
      <label className="flex items-center gap-3">
        <Checkbox disabled defaultChecked />
        Disabled and checked
      </label>
      <label className="flex items-center gap-3">
        <Checkbox readOnly defaultChecked />
        Read-only
      </label>
      <label className="flex items-center gap-3">
        <Checkbox indeterminate />
        Indeterminate
      </label>
      <label className="flex items-center gap-3">
        <Checkbox aria-invalid />
        Invalid
      </label>
      <label className="flex items-center gap-3">
        <Checkbox aria-invalid defaultChecked />
        Invalid and checked
      </label>
    </div>
  )
}

Tout sélectionner

Dans un <CheckboxGroup />, une case à cocher avec parent coche toutes les valeurs de allValues. Elle devient indéterminée lorsque seules certaines sont cochées.

"use client"

import * as React from "react"

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

const fruits = ["Apple", "Banana", "Cherry", "Mango", "Peach"]

export function CheckboxSelectAll() {
  const [value, setValue] = React.useState<string[]>(["Banana"])

  return (
    <div className="text-sm">
      <CheckboxGroup
        aria-label="Fruits"
        value={value}
        onValueChange={setValue}
        allValues={fruits}
      >
        <label className="flex items-center gap-3">
          <Checkbox parent />
          <span>
            Select all{" "}
            <span className="text-muted-foreground">
              ({value.length}/{fruits.length})
            </span>
          </span>
        </label>
        <div className="flex flex-col gap-3 ps-7">
          {fruits.map((fruit) => (
            <label key={fruit} className="flex items-center gap-3">
              <Checkbox value={fruit} />
              {fruit}
            </label>
          ))}
        </div>
      </CheckboxGroup>
    </div>
  )
}

Groupes imbriqués

Les groupes s’imbriquent. Chaque parent reflète l’état du groupe situé juste en dessous, et le parent de plus haut niveau couvre tout.

"use client"

import * as React from "react"

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

const userPermissions = ["users.read", "users.write", "users.delete"]
const billingPermissions = ["billing.read", "billing.write"]

export function CheckboxNestedGroups() {
  const [users, setUsers] = React.useState<string[]>(["users.read"])
  const [billing, setBilling] = React.useState<string[]>([])

  return (
    <div className="text-sm">
      <CheckboxGroup
        aria-label="Permissions"
        value={[...users, ...billing]}
        onValueChange={(next) => {
          setUsers(next.filter((value) => value.startsWith("users.")))
          setBilling(next.filter((value) => value.startsWith("billing.")))
        }}
        allValues={[...userPermissions, ...billingPermissions]}
      >
        <label className="flex items-center gap-3">
          <Checkbox parent />
          All permissions
        </label>
        <div className="flex flex-col gap-3 ps-7">
          <CheckboxGroup
            aria-label="Users"
            value={users}
            onValueChange={setUsers}
            allValues={userPermissions}
          >
            <label className="flex items-center gap-3">
              <Checkbox parent />
              Users
            </label>
            <div className="flex flex-col gap-3 ps-7">
              {userPermissions.map((permission) => (
                <label key={permission} className="flex items-center gap-3">
                  <Checkbox value={permission} />
                  {permission}
                </label>
              ))}
            </div>
          </CheckboxGroup>
          <CheckboxGroup
            aria-label="Billing"
            value={billing}
            onValueChange={setBilling}
            allValues={billingPermissions}
          >
            <label className="flex items-center gap-3">
              <Checkbox parent />
              Billing
            </label>
            <div className="flex flex-col gap-3 ps-7">
              {billingPermissions.map((permission) => (
                <label key={permission} className="flex items-center gap-3">
                  <Checkbox value={permission} />
                  {permission}
                </label>
              ))}
            </div>
          </CheckboxGroup>
        </div>
      </CheckboxGroup>
    </div>
  )
}

Contrôlé

Passez checked et onCheckedChange pour garder l’état dans votre propre code.

"use client"

import * as React from "react"

import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"

export function CheckboxControlled() {
  const [checked, setChecked] = React.useState(false)

  return (
    <div className="flex flex-col items-start gap-3">
      <label className="flex items-center gap-3 text-sm">
        <Checkbox checked={checked} onCheckedChange={setChecked} />
        Controlled ({checked ? "on" : "off"})
      </label>
      <Button variant="outline" size="sm" onClick={() => setChecked(!checked)}>
        Toggle from outside
      </Button>
    </div>
  )
}

Form

Un champ masqué soumet name et value comme une case à cocher native, et required bloque la soumission tant qu’elle n’est pas cochée.

"use client"

import * as React from "react"

import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"

export function CheckboxForm() {
  const [submitted, setSubmitted] = React.useState<string>()

  return (
    <form
      className="flex flex-col items-start gap-3 text-sm"
      onSubmit={(event) => {
        event.preventDefault()
        const data = new FormData(event.currentTarget)
        setSubmitted(JSON.stringify(Object.fromEntries(data.entries())))
      }}
    >
      <label className="flex items-center gap-3">
        <Checkbox name="terms" required />I agree to the terms
      </label>
      <label className="flex items-center gap-3">
        <Checkbox name="newsletter" value="weekly" defaultChecked />
        Weekly newsletter
      </label>
      <Button type="submit" size="sm">
        Submit
      </Button>
      <output className="text-muted-foreground">
        {submitted ?? "Nothing submitted yet."}
      </output>
    </form>
  )
}

Libellé adjacent

Lorsque le libellé ne peut pas envelopper la case, rendez la case à cocher comme un <button> avec nativeButton et pointez le libellé vers elle avec htmlFor.

import { Checkbox } from "@/components/ui/checkbox"

export function CheckboxSiblingLabel() {
  return (
    <div className="flex items-center gap-2 text-sm">
      <Checkbox id="terms" nativeButton render={<button />} />
      <label htmlFor="terms">Accept terms and conditions</label>
    </div>
  )
}

Cartes

Enveloppez toute une carte dans le libellé pour que la carte serve de zone de clic, et stylisez-la avec has-data-checked.

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

const addOns = [
  { value: "analytics", title: "Analytics", text: "Dashboards and exports." },
  { value: "backups", title: "Backups", text: "Daily snapshots, 30 days." },
]

export function CheckboxCards() {
  return (
    <CheckboxGroup
      aria-label="Add-ons"
      defaultValue={["analytics"]}
      className="w-full max-w-md"
    >
      <div className="grid gap-3 sm:grid-cols-2">
        {addOns.map((addOn) => (
          <label
            key={addOn.value}
            className="flex items-start gap-3 rounded-xl border p-4 text-sm transition-colors has-data-checked:border-primary"
          >
            <span className="flex h-5 items-center">
              <Checkbox value={addOn.value} />
            </span>
            <span className="flex flex-col gap-0.5">
              <span className="leading-5 font-medium">{addOn.title}</span>
              <span className="text-muted-foreground">{addOn.text}</span>
            </span>
          </label>
        ))}
      </div>
    </CheckboxGroup>
  )
}

Contenu long

La case reste sur la première ligne tandis qu’un long libellé et du texte sans coupure passent à la ligne à côté.

import { Checkbox } from "@/components/ui/checkbox"

export function CheckboxLongContent() {
  return (
    <label className="flex w-64 max-w-full items-start gap-3 text-sm">
      <span className="flex h-5 items-center">
        <Checkbox />
      </span>
      <span className="flex min-w-0 flex-col gap-0.5 wrap-anywhere">
        <span className="leading-5 font-medium">
          A label long enough to wrap onto a second and even a third line in a
          narrow container
        </span>
        <span className="text-muted-foreground">
          averyveryverylongunbrokenstringthatwouldotherwiseescapeitscontainer
        </span>
      </span>
    </label>
  )
}

De droite à gauche

La case se place du côté du début de la ligne et le libellé suit le sens de lecture.

import { Checkbox } from "@/components/ui/checkbox"

export function CheckboxRtl() {
  return (
    <div dir="rtl" className="flex flex-col gap-3 text-sm">
      <label className="flex items-center gap-3">
        <Checkbox defaultChecked />
        تذكر هذا الجهاز
      </label>
      <label className="flex max-w-sm items-start gap-3">
        <span className="flex h-5 items-center">
          <Checkbox />
        </span>
        <span className="flex flex-col gap-0.5">
          <span className="leading-5 font-medium">الإشارات والردود</span>
          <span className="text-muted-foreground">
            سنرسل لك إشعارات فقط حول نشاط منشوراتك.
          </span>
        </span>
      </label>
    </div>
  )
}

Clavier

ToucheAction
SpaceCoche ou décoche la case.
EnterSoumet le formulaire auquel appartient la case à cocher, comme une case native. Ne la bascule jamais.
TabDéplace le focus vers la case à cocher suivante.

Accessibilité

  • Enveloppez la case à cocher et son texte dans un <label>. Le libellé nomme la case, et le survoler ou l’appuyer donne à la case le même retour que le survol de la case elle-même.
  • Donnez à chaque <CheckboxGroup /> un aria-label ou aria-labelledby pour que les lecteurs d’écran annoncent à quoi sert le groupe.
  • La zone de clic dépasse la case de 16 px, et grandit sur écran tactile.
  • La coche se dessine lorsqu’elle est cochée. Avec la réduction des animations, elle apparaît sans animation du tracé.

Référence de l’API

Construit sur la case à cocher et le groupe de cases à cocher de Base UI. Les deux acceptent les props de la primitive qu’ils enveloppent.

Checkbox

PropTypePar défaut
checked
boolean–
defaultChecked
booleanfalse
onCheckedChange
(checked: boolean, details) => void–
indeterminateAffiche un tiret : ni cochée ni décochée.
booleanfalse
disabled
booleanfalse
readOnlyFocusable, mais la valeur ne peut pas changer.
booleanfalse
required
booleanfalse
nameSoumis avec le formulaire lorsqu’elle est cochée.
string–
valueIdentifie la case dans un groupe et correspond à ce que le formulaire soumet. Se rabat sur name, puis sur « on ».
string–
uncheckedValueSoumis lorsqu’elle est décochée. Rien par défaut.
string–
parentContrôle toutes les valeurs de allValues du groupe. Uniquement dans un CheckboxGroup.
booleanfalse
inputRef
Ref<HTMLInputElement>–
nativeButtonÀ définir sur true lorsque render est un <button>.
booleanfalse
render
ReactElement | (props, state) => ReactElement<span>
AttributDescription
data-slot="checkbox"Ciblez la boîte en CSS.
data-checkedPrésent lorsqu’elle est cochée.
data-uncheckedPrésent lorsqu’elle est décochée.
data-indeterminatePrésent lorsque l’état est indéterminé.
data-disabledPrésent lorsque l’élément est désactivé.
data-readonlyPrésent en lecture seule.
data-requiredPrésent lorsqu’elle est requise.
data-invalidPrésent lorsqu’elle est invalide dans un Field de Base UI.

CheckboxGroup

PropTypePar défaut
valueValeurs des cases cochées.
string[]–
defaultValue
string[]–
onValueChange
(value: string[], details) => void–
allValuesToutes les valeurs du groupe. Requis pour une case à cocher parente.
string[]–
disabled
booleanfalse
render
ReactElement | (props, state) => ReactElement<div>
AttributDescription
data-slot="checkbox-group"Ciblez le groupe en CSS.
data-disabledPrésent lorsque le groupe est désactivé.

Voir aussi

Utilisé dans les blocks

Des blocks qui s’appuient sur Checkbox.