文档演练博客

复选框组

一组交互式按钮，可一次选择多个选项。

View source Report an issue View in Playground

FunSeriousSmart

<CheckboxGroup.Root defaultValue={["1"]} name="example">
	<CheckboxGroup.Item value="1">Fun</CheckboxGroup.Item>
	<CheckboxGroup.Item value="2">Serious</CheckboxGroup.Item>
	<CheckboxGroup.Item value="3">Smart</CheckboxGroup.Item>
</CheckboxGroup.Root>

API 参考

¥API Reference

此组件基于 div 元素并支持常用边距属性。

¥This component is based on the div element and supports common margin props.

根

¥Root

包含复选框组的所有部分。

¥Contains all the parts of a checkbox group.

Prop	Type	Default
`asChild`	`boolean`	No default value
`size`	`Responsive<"1" \| "2" \| "3">`	`"2"`
`variant`	`"classic" \| "surface" \| "soft"`	`"surface"`
`color`	`enum`	No default value
`highContrast`	`boolean`	No default value

项目

¥Item

组中可勾选的项目。

¥An item in the group that can be checked.

示例

¥Examples

尺寸

¥Size

使用 size 属性控制复选框的大小。

¥Use the size prop to control the checkbox size.

<Flex align="center" gap="2">
	<CheckboxGroup.Root size="1" defaultValue="1">
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root size="2" defaultValue="1">
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root size="3" defaultValue="1">
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>
</Flex>

变体

¥Variant

使用 variant 属性控制复选框的视觉样式。

¥Use the variant prop to control the visual style of the checkboxes.

<Flex gap="2">
	<Flex direction="column" asChild gap="2">
		<CheckboxGroup.Root variant="surface" defaultValue="1">
			<CheckboxGroup.Item value="1" />
			<CheckboxGroup.Item value="2" />
		</CheckboxGroup.Root>
	</Flex>

	<Flex direction="column" asChild gap="2">
		<CheckboxGroup.Root variant="classic" defaultValue="1">
			<CheckboxGroup.Item value="1" />
			<CheckboxGroup.Item value="2" />
		</CheckboxGroup.Root>
	</Flex>

	<Flex direction="column" asChild gap="2">
		<CheckboxGroup.Root variant="soft" defaultValue="1">
			<CheckboxGroup.Item value="1" />
			<CheckboxGroup.Item value="2" />
		</CheckboxGroup.Root>
	</Flex>
</Flex>

颜色

¥Color

使用 color 属性指定特定的 color。

¥Use the color prop to assign a specific color.

<Flex gap="2">
	<CheckboxGroup.Root color="indigo" defaultValue="1">
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root color="cyan" defaultValue="1">
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root color="orange" defaultValue="1">
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root color="crimson" defaultValue="1">
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>
</Flex>

高对比度

¥High-contrast

使用 highContrast 属性增加与背景的颜色对比度。

¥Use the highContrast prop to increase color contrast with the background.

<Grid rows="2" gap="2" display="inline-grid" flow="column">
	<CheckboxGroup.Root color="indigo" defaultValue="1">
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root color="indigo" defaultValue="1" highContrast>
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root color="cyan" defaultValue="1">
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root color="cyan" defaultValue="1" highContrast>
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root color="orange" defaultValue="1">
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root color="orange" defaultValue="1" highContrast>
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root color="crimson" defaultValue="1">
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root color="crimson" defaultValue="1" highContrast>
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root color="gray" defaultValue="1">
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>

	<CheckboxGroup.Root color="gray" defaultValue="1" highContrast>
		<CheckboxGroup.Item value="1" />
	</CheckboxGroup.Root>
</Grid>

对齐方式

¥Alignment

在 Text 中组合 CheckboxGroup.Item，会自动将其与第一行文本居中。

¥Composing CheckboxGroup.Item within Text automatically centers it with the first line of text.

<Flex direction="column" gap="3">
	<CheckboxGroup.Root size="1" defaultValue="1">
		<Text as="label" size="2">
			<Flex gap="2">
				<CheckboxGroup.Item value="1" /> Default
			</Flex>
		</Text>

		<Text as="label" size="2">
			<Flex gap="2">
				<CheckboxGroup.Item value="2" /> Compact
			</Flex>
		</Text>
	</CheckboxGroup.Root>

	<CheckboxGroup.Root size="2" defaultValue="1">
		<Text as="label" size="3">
			<Flex gap="2">
				<CheckboxGroup.Item value="1" /> Default
			</Flex>
		</Text>

		<Text as="label" size="3">
			<Flex gap="2">
				<CheckboxGroup.Item value="2" /> Compact
			</Flex>
		</Text>
	</CheckboxGroup.Root>

	<CheckboxGroup.Root size="3" defaultValue="1">
		<Text as="label" size="4">
			<Flex gap="2">
				<CheckboxGroup.Item value="1" /> Default
			</Flex>
		</Text>

		<Text as="label" size="4">
			<Flex gap="2">
				<CheckboxGroup.Item value="2" /> Compact
			</Flex>
		</Text>
	</CheckboxGroup.Root>
</Flex>

它还能自动与多行文本对齐。

¥It is automatically well-aligned with multi-line text too.

已禁用

¥Disabled

使用原生 disabled 属性创建禁用的复选框。

¥Use the native disabled attribute to create a disabled checkbox.

OffOn

<Flex direction="column" gap="2">
	<CheckboxGroup.Root defaultValue="2">
		<CheckboxGroup.Item value="1">Off</CheckboxGroup.Item>
		<CheckboxGroup.Item value="2">On</CheckboxGroup.Item>
	</CheckboxGroup.Root>

	<CheckboxGroup.Root defaultValue="2">
		<CheckboxGroup.Item value="1" disabled>
			Off
		</CheckboxGroup.Item>
		<CheckboxGroup.Item value="2" disabled>
			On
		</CheckboxGroup.Item>
	</CheckboxGroup.Root>
</Flex>

Previous复选框

Next复选框卡片

概览

主题

布局

排版

组件

实用工具

复选框组