组件

Checkbox Group

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

<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 参考

此组件基于 div 元素,并支持通用 margin 属性

Root

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

属性类型默认值
asChild
boolean
无默认值
size
响应式<"1" | "2" | "3">
"2"
variant
"classic" | "surface" | "soft"
"surface"
color
enum
无默认值
highContrast
boolean
无默认值

Item

组中可以被选中的一项。

示例

尺寸

使用 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 属性来控制复选框的视觉样式。

<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 属性来指定特定的颜色

<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>

高对比度

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

<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>

对齐

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

<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>

它也可以自动与多行文本良好对齐。

禁用

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

<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>
上一个Checkbox