Salt la conținutul principal

Prezentare generală

Utilizați Checkbox atunci când fiecare opțiune poate fi selectată independent. Pentru o alegere reciproc exclusivă, utilizați RadioGroup.

Utilizare

Stare necontrolată

Utilizați defaultChecked pentru a seta starea inițială de bifare. Caseta de bifare gestionează modificările ulterioare.
O casetă de selectare bifată și denumită contribuie cu valoarea sa la un formular. Setați uncheckedValue dacă formularul trebuie să trimită și o valoare atunci când aceasta nu este bifată.

Aspect și interacțiune

Comparați stările bifată, nedeterminată și dezactivată, apoi alegeți independent culoarea, dimensiunea, forma și varianta. Exemplele activate pot fi comutate. Tasta Tab focalizează caseta de selectare, iar bara de spațiu îi schimbă starea. Selectarea etichetei sale îi schimbă, de asemenea, starea. Utilizați disabled pentru a împiedica interacțiunea sau readOnly atunci când valoarea trebuie să rămână neschimbată, iar controlul trebuie să rămână focalizabil. Păstrați semnificația în etichetă, în loc să o comunicați doar prin culoare.

Stare controlată

Transmiteți checked și actualizați-l cu onCheckedChange pentru a gestiona aceeași preferință în starea React. Funcția callback primește următoarea valoare booleană și detaliile evenimentului.

Stare nedeterminată

O casetă de bifare nedeterminată reprezintă o selecție parțială. Derivați-o din opțiunile secundare, independent de starea de bifare a casetei de bifare.

Părți și conținut personalizat

Checkbox asamblează rădăcina stilizată și pictogramele sale implicite de bifare și stare nedeterminată. Utilizați Checkbox.Root cu Checkbox.Indicator pentru a controla conținutul indicatorului. Root controlează starea și aspectul casetei; Indicator redă conținutul pe care îl furnizați.
CheckboxRootProps și CheckboxIndicatorProps sunt tipuri publice exportate din twenty-ui/primitives/input. Ambele părți acceptă atribute native, handlere, referințe, render și callbackuri className și style bazate pe stare. ref al Root vizează controlul vizibil; inputRef vizează intrarea nativă. Referința părții vizează elementul redat de aceasta. Transmiteți nativeButton cu render={<button />} atunci când înlocuiți Root cu un buton. Proprietățile de aspect aparțin Root; clasele și stilurile explicite sunt îmbinate cu valorile implicite. Indicator primește starea de bifare și starea nedeterminată, inclusiv starea de tranziție. Setați keepMounted pentru a păstra un indicator nebifat în DOM; stilizarea implicită îl ascunde prin opacitate. Suprascrieți style sau className pentru tranziții personalizate. Asamblarea apelabilă și tipul său CheckboxProps rămân acceptate. Înlocuiți asamblarea cu Root și partea sa atunci când furnizați pictograme personalizate, în loc să adăugați altă parte la elementele copil ale asamblării. Pentru resetarea controlată a formularului, gestionați onReset al formularului și restaurați checked la valoarea inițială. Base UI 1.8 nu restabilește starea componentelor necontrolate la resetarea nativă a formularului. required, form, value și uncheckedValue păstrează comportamentul intrării native din amonte.

Proprietăți

Referința este generată din tipurile publice ale componentei. Atributele native, inclusiv numele accesibile și gestionarii de evenimente, sunt acceptate și pe părțile care redau elemente.
boolean
Whether the checkbox is currently ticked.To render an uncontrolled checkbox, use the defaultChecked prop instead.
string | ((state: CheckboxRootState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
"accent" | "success" | "warning"
implicit:"accent"
Color used while the checkbox is checked or indeterminate.
boolean
implicit:"false"
Whether the checkbox is initially ticked.To render a controlled checkbox, use the checked prop instead.
boolean
implicit:"false"
Whether the component should ignore user interaction.
string
Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
boolean
implicit:"true"
Adds padding and a hover background around the box.
string
The id of the input element.
boolean
implicit:"false"
Whether the checkbox is in a mixed state: neither ticked, nor unticked.
Ref<HTMLInputElement>
A ref to access the hidden <input> element.
string
Identifies the field when a form is submitted.
boolean
implicit:"false"
Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.
((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)
Event handler called when the checkbox is ticked or unticked.
boolean
implicit:"false"
Whether the checkbox controls a group of child checkboxes.Must be used in a Checkbox Group.
boolean
implicit:"false"
Whether the user should be unable to tick or untick the checkbox.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CheckboxRootState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
boolean
implicit:"false"
Whether the user must tick the checkbox before submitting a form.
"round" | "square"
implicit:"square"
Corner shape of the box.
"md" | "sm"
implicit:"sm"
Visual size of the checkbox.
CSSProperties | ((state: CheckboxRootState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
string
The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.
string
The checkbox’s value. Identifies it within a Checkbox Group, falling back to name when omitted. When submitting a form, a checked box submits value; with no value, it submits the native “on”.
"outline" | "soft" | "solid"
implicit:"solid"
Visual style of the box: filled, outlined, or tinted.

Checkbox.Root

boolean
Whether the checkbox is currently ticked.To render an uncontrolled checkbox, use the defaultChecked prop instead.
string | ((state: CheckboxRootState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
"accent" | "success" | "warning"
implicit:"accent"
Color used while the checkbox is checked or indeterminate.
boolean
implicit:"false"
Whether the checkbox is initially ticked.To render a controlled checkbox, use the checked prop instead.
boolean
implicit:"false"
Whether the component should ignore user interaction.
string
Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
boolean
implicit:"true"
Adds padding and a hover background around the box.
string
The id of the input element.
boolean
implicit:"false"
Whether the checkbox is in a mixed state: neither ticked, nor unticked.
Ref<HTMLInputElement>
A ref to access the hidden <input> element.
string
Identifies the field when a form is submitted.
boolean
implicit:"false"
Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.
((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)
Event handler called when the checkbox is ticked or unticked.
boolean
implicit:"false"
Whether the checkbox controls a group of child checkboxes.Must be used in a Checkbox Group.
boolean
implicit:"false"
Whether the user should be unable to tick or untick the checkbox.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CheckboxRootState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
boolean
implicit:"false"
Whether the user must tick the checkbox before submitting a form.
"round" | "square"
implicit:"square"
Corner shape of the box.
"md" | "sm"
implicit:"sm"
Visual size of the checkbox.
CSSProperties | ((state: CheckboxRootState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
string
The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.
string
The checkbox’s value. Identifies it within a Checkbox Group, falling back to name when omitted. When submitting a form, a checked box submits value; with no value, it submits the native “on”.
"outline" | "soft" | "solid"
implicit:"solid"
Visual style of the box: filled, outlined, or tinted.

Checkbox.Indicator

string | ((state: CheckboxIndicatorState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
boolean
implicit:"false"
Whether to keep the element in the DOM when the checkbox is not checked.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CheckboxIndicatorState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
CSSProperties | ((state: CheckboxIndicatorState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.