复选框

一种允许用户在选中和未选中之间切换的控件。

import * as React from "react";
import { Checkbox } from "radix-ui";
import { CheckIcon } from "@radix-ui/react-icons";
import "./styles.css";

const CheckboxDemo = () => (
	<form>
		<div style={{ display: "flex", alignItems: "center" }}>
			<Checkbox.Root className="CheckboxRoot" defaultChecked id="c1">
				<Checkbox.Indicator className="CheckboxIndicator">
					<CheckIcon />
				</Checkbox.Indicator>
			</Checkbox.Root>
			<label className="Label" htmlFor="c1">
				Accept terms and conditions.
			</label>
		</div>
	</form>
);

export default CheckboxDemo;

Features

支持不确定状态。
完全的键盘导航。
可以是受控或非受控的。

结构

导入所有部分并将它们组合在一起。

import { Checkbox } from "radix-ui";

export default () => (
	<Checkbox.Root>
		<Checkbox.Indicator />
	</Checkbox.Root>
);

API 参考

Root

包含复选框的所有部分。当在 form 中使用时，将渲染一个 input 以确保事件正确传播。

Prop	Type	Default
`asChild`	`boolean`	`false`
`defaultChecked`	`boolean \| 'indeterminate'`	No default value
`checked`	`boolean \| 'indeterminate'`	No default value
`onCheckedChange`	`function`	No default value
`disabled`	`boolean`	No default value
`required`	`boolean`	No default value
`name`	`string`	No default value
`value`	`string`	`on`

Data attribute	Values
`[data-state]`	`"checked" \| "unchecked" \| "indeterminate"`
`[data-disabled]`	禁用时存在

Indicator

在复选框处于选中或不确定状态时渲染。您可以直接为此元素设置样式，或者可以将其作为包装器放入图标，或者两者都可以。

Prop	Type	Default
`asChild`	`boolean`	`false`
`forceMount`	`boolean`	No default value

Data attribute	Values
`[data-state]`	`"checked" \| "unchecked" \| "indeterminate"`
`[data-disabled]`	禁用时存在

示例

不确定状态

您可以通过控制其状态将复选框设置为 indeterminate。

import { DividerHorizontalIcon, CheckIcon } from "@radix-ui/react-icons";
import { Checkbox } from "radix-ui";

export default () => {
	const [checked, setChecked] = React.useState("indeterminate");

	return (
		<>
			<StyledCheckbox checked={checked} onCheckedChange={setChecked}>
				<Checkbox.Indicator>
					{checked === "indeterminate" && <DividerHorizontalIcon />}
					{checked === true && <CheckIcon />}
				</Checkbox.Indicator>
			</StyledCheckbox>

			<button
				type="button"
				onClick={() =>
					setChecked((prevIsChecked) =>
						prevIsChecked === "indeterminate" ? false : "indeterminate",
					)
				}
			>
				切换不确定状态
			</button>
		</>
	);
};

解耦隐藏输入

默认情况下，Checkbox.Root 会渲染一个视觉上隐藏的 input，用于表单提交。要重新组合、移动或排除该输入，您可以改用其较低层级的部分来构建复选框。

重要： 这些部分尚不稳定，并以 unstable_ 为前缀，因此其 API 可能会在未来版本中发生变化。

Checkbox.unstable_Provider 提供复选框状态，并接受与表单相关的属性（name、value、checked、defaultChecked、required、disabled、onCheckedChange）。
Checkbox.unstable_Trigger 是包裹 Checkbox.Indicator 的交互式按钮。
Checkbox.unstable_BubbleInput 是 Checkbox.Root 默认渲染的视觉上隐藏的输入。不需要表单提交时，可以省略它。

import { Checkbox } from "radix-ui";

export default () => (
	<Checkbox.unstable_Provider name="terms">
		<Checkbox.unstable_Trigger>
			<Checkbox.Indicator />
		</Checkbox.unstable_Trigger>
		<Checkbox.unstable_BubbleInput />
	</Checkbox.unstable_Provider>
);

可访问性

遵循三态复选框 WAI-ARIA 设计模式。

键盘交互

Key	Description
`Space`	选中/取消选中复选框。

上一篇头像 Avatar

下一篇可折叠组件 Collapsible

在 GitHub 上编辑此页面

概览 Overview

指南 Guides

组件 Components

通用工具 Utilities

复选框

Features