组件 · 输入
Checkbox
A square box for a yes or no that is saved with a form, or an option attached to an action.
import { Checkbox } from "@botiverse/raft-ui";A checkbox is a yes or no that takes effect when the form is saved. Checked, it is an ink block with the check mark knocked out of it: it shows a value, not "you are here", so it is never yellow.
When to use
| Situation | Use |
|---|---|
| A yes or no in a form that is saved: a dialog, a drawer, the wide form dialog | Checkbox |
| An option attached to an action, such as sending a message as a task | Checkbox in the action's toolbar (ComposerToolbarLabel, Composer) |
| Choosing several items in a list or a multi-select | Checkbox, or CheckboxIndicator in a row that owns the semantics |
| A yes or no that applies at once | Switch |
| One of several answers | RadioGroup |
Which controls apply at once and which are saved is in Forms.
Anatomy
Checkbox: the 20px box, with a hidden native input that holds the state. Required.- A label: wrap the checkbox and its text in a
<label>(Label, orFieldItemwithFieldLabelin a Field). Make the<label>a flex row withgap-2and the label's type: the box takes a box one line of the label tall, so it centers on the text's line by itself, on the first line withitems-start(use it when the label can wrap) and on the one line withitems-centerat any min-height. Don't add amargin-top(Alignment). CheckboxIndicator: the box drawn on its own, with no input or role, for a row or menu item that already has checkbox semantics.
States
The checked, disabled and focus looks follow States.
- Unchecked: an empty box with an ink border.
- Checked: an ink block with the check mark knocked out.
- Indeterminate: an ink block with a minus, for a box that stands for a group whose items are partly checked.
Behavior
- Make the whole label clickable, not only the box. In a
<label>row the box's hit area reaches 4px past its line, half the 8px gap to the next option, so a tap between two lands on the nearer. On its own it is 44 × 44 on a touch screen and 44 × 36 with a mouse.
Content
- Set the label in
text-calloutat weight 600. - In a form, add a line below the label that says what happens when the box is left unchecked.
Accessibility
Checkbox wraps Base UI Checkbox. Its hidden native input drives the checked, disabled and focus state, and the focus ring is drawn on the box (States).
- Give every checkbox a name: a wrapping
<label>, aFieldLabel, oraria-labelwhen there is no visible text (selecting a row). CheckboxIndicatorisaria-hidden. The element that holds it must carry the role and the checked state.
Rules
- Keep the box square. Don't use
shape="circle": round is only for switches and radios (Shape).
API
Checkbox
| Prop | 类型 | 默认值 |
|---|---|---|
| "circle" | "square" | "square" | |
| Whether the checkbox is currently ticked. | boolean | undefined |
| Whether the checkbox is initially ticked. | boolean | false |
| Whether the component should ignore user interaction. | boolean | false |
| Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form. | string | |
| The id of the input element. | string | |
| Whether the checkbox is in a mixed state: neither ticked, nor unticked. | boolean | false |
| A ref to access the hidden `<input>` element. | ((instance: HTMLInputElement | null) => void | (() => void | { [UNDEFINED_VOID_ONLY]: never; }) | DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) | RefObject<HTMLInputElement | null> | |
| Identifies the field when a form is submitted. | string | undefined |
| 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. | boolean | false |
| Event handler called when the checkbox is ticked or unticked. | (checked: boolean, eventDetails: CheckboxRootChangeEventDetails) => void | |
| Whether the checkbox controls a group of child checkboxes. | boolean | false |
| Whether the user should be unable to tick or untick the checkbox. | boolean | false |
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) | |
| Whether the user must tick the checkbox before submitting a form. | boolean | false |
| 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](https://base-ui.com/react/components/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". | string |
Also takes the attributes of its element.
CheckboxIndicator
| Prop | 类型 | 默认值 |
|---|---|---|
| boolean | ||
| boolean | false | |
| CheckboxIndicatorMark | "check" | |
| boolean | false | |
| "circle" | "square" | "square" |
Also takes the attributes of its element.
相关组件
改动
- 0.6.0 · Breaking ChangesProps that no longer change anything are removed:
Badgeuppercase;Checkboxsize,variant,color;Statuspulse,attention(status never animates);Switch/SwitchThumbsize;SidebarItemvariant;SidebarItemCount/SidebarItemIndicatorvariantandappearance(the count is always the pink sticker, the indicator the yellow @);NotificationCenterActionButtonvariant;DrawerContentwidth(one-go forms use the wideDialog);AppRailItemIndicatorattention;AppRailItemAttentionchildren;Stepssize,track,renderIndicator,renderTraveler;FilePreviewBadgetype,color. Remove them at call sites. - 0.6.0 · Added
CheckboxIndicator: the 20px checkbox box as a visual part for picker rows.