Panoramica
UsaCheckbox quando ogni opzione può essere selezionata indipendentemente. Per una scelta mutuamente esclusiva, usa RadioGroup.
Utilizzo
Stato non controllato
UsadefaultChecked per impostare lo stato iniziale della selezione. La casella di controllo gestisce le modifiche successive.
uncheckedValue se il modulo deve inviare un valore anche quando non è selezionata.
Aspetto e interazione
Confronta gli stati selezionato, indeterminato e disabilitato, quindi scegli in modo indipendente colore, dimensione, forma e variante. Gli esempi abilitati possono essere attivati o disattivati.
Tab porta il focus sulla casella di controllo e Spazio ne cambia lo stato. Facendo clic sulla relativa etichetta ne cambia anch’esso lo stato. Usa
disabled per impedire l’interazione oppure readOnly quando il valore deve rimanere invariato mantenendo il controllo selezionabile tramite focus. Mantieni il significato nell’etichetta anziché comunicarlo solo tramite il colore.
Stato controllato
Passachecked e aggiornalo con onCheckedChange per gestire la stessa preferenza nello stato di React. Il callback riceve il valore booleano successivo e i dettagli dell’evento.
Stato indeterminato
Una casella di controllo indeterminata rappresenta una selezione parziale. Derivalo dalle opzioni figlie indipendentemente dallo stato selezionato della casella di controllo.Parti e contenuti personalizzati
Checkbox assembla la radice con stile e le relative icone di selezione e stato indeterminato predefinite. Usa Checkbox.Root con Checkbox.Indicator per gestire il contenuto dell’indicatore. Root gestisce lo stato e l’aspetto della casella; Indicator esegue il rendering del contenuto fornito.
CheckboxRootProps e CheckboxIndicatorProps sono tipi pubblici esportati da twenty-ui/primitives/input. Entrambe le parti accettano attributi nativi, gestori, ref, render e callback className e style basate sullo stato. Il ref di Root punta al controllo visibile; inputRef punta all’input nativo. Il ref della parte punta al relativo elemento renderizzato. Passa nativeButton con render={<button />} quando sostituisci Root con un pulsante. Le props dell’aspetto appartengono a Root; classi e stili espliciti vengono uniti a quelli predefiniti.
Indicator riceve lo stato selezionato e indeterminato, incluso lo stato di transizione. Imposta keepMounted per mantenere nel DOM un indicatore non selezionato; lo stile predefinito lo nasconde tramite opacità. Sovrascrivi il relativo style o className per transizioni personalizzate.
L’assembly richiamabile e il relativo tipo CheckboxProps rimangono supportati. Sostituisci l’assembly con Root e la relativa parte quando fornisci icone personalizzate, anziché aggiungere un’altra parte ai figli dell’assembly.
Per il ripristino di un modulo controllato, gestisci onReset del modulo e ripristina checked al valore iniziale. Base UI 1.8 non ripristina lo stato dei componenti non controllati al ripristino nativo del modulo. required, form, value e uncheckedValue mantengono il comportamento dell’input nativo upstream.
Props
Il riferimento viene generato dai tipi pubblici del componente. Gli attributi nativi, inclusi i nomi accessibili e i gestori degli eventi, sono accettati anche nelle parti che eseguono il rendering degli elementi.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"
predefinito:"accent"
Color used while the checkbox is checked or indeterminate.
boolean
predefinito:"false"
Whether the checkbox is initially ticked.To render a controlled checkbox, use the
checked prop instead.boolean
predefinito:"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
predefinito:"true"
Adds padding and a hover background around the box.
string
The id of the input element.
boolean
predefinito:"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
predefinito:"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
predefinito:"false"
Whether the checkbox controls a group of child checkboxes.Must be used in a Checkbox Group.
boolean
predefinito:"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
predefinito:"false"
Whether the user must tick the checkbox before submitting a form.
"round" | "square"
predefinito:"square"
Corner shape of the box.
"md" | "sm"
predefinito:"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"
predefinito:"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"
predefinito:"accent"
Color used while the checkbox is checked or indeterminate.
boolean
predefinito:"false"
Whether the checkbox is initially ticked.To render a controlled checkbox, use the
checked prop instead.boolean
predefinito:"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
predefinito:"true"
Adds padding and a hover background around the box.
string
The id of the input element.
boolean
predefinito:"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
predefinito:"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
predefinito:"false"
Whether the checkbox controls a group of child checkboxes.Must be used in a Checkbox Group.
boolean
predefinito:"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
predefinito:"false"
Whether the user must tick the checkbox before submitting a form.
"round" | "square"
predefinito:"square"
Corner shape of the box.
"md" | "sm"
predefinito:"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"
predefinito:"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
predefinito:"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.