复选框

允许用户在选中与未选中状态之间切换的控件。

View code

Accept terms and conditions.

功能特性

支持不确定状态。
完整的键盘导航支持。
支持受控与非受控模式。

安装

通过命令行安装该组件。

$ npm add reka-ui

结构

导入所有组成部分并进行拼装。

vue

<script setup>
import { CheckboxGroupRoot, CheckboxIndicator, CheckboxRoot } from 'reka-ui'
</script>

<template>
  <CheckboxRoot>
    <CheckboxIndicator />
  </CheckboxRoot>

  <!-- 或支持数组形式 -->
  <CheckboxGroupRoot>
    <CheckboxRoot>
      <CheckboxIndicator />
    </CheckboxRoot>
  </CheckboxGroupRoot>
</template>

API 参考

根组件 (Root)

包含复选框的所有组成部分。在 form 表单内使用时还会渲染一个 input 元素以确保事件正确传播。

Prop	Default	Type
`as`	`'button'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`defaultValue`		`boolean \| 'indeterminate'` The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
`disabled`		`boolean` When `true`, prevents the user from interacting with the checkbox
`id`		`string` Id of the element
`modelValue`		`boolean \| 'indeterminate' \| null` The controlled value of the checkbox. Can be binded with v-model.
`name`		`string` The name of the field. Submitted with its owning form as part of a name/value pair.
`required`		`boolean` When `true`, indicates that the user must set the value before the owning form can be submitted.
`value`	`'on'`	`AcceptableValue` The value given as data when submitted with a `name`.

Emit	Payload
`update:modelValue`	`[value: boolean \| 'indeterminate']` Event handler called when the value of the checkbox changes.

Slots (default)	Payload
`modelValue`	`false \| true \| 'indeterminate'` Current value
`state`	`CheckedState` Current state

Data Attribute	Value
`[data-state]`	`"checked" \| "unchecked" \| "indeterminate"`
`[data-disabled]`	禁用时出现

指示器 (Indicator)

当复选框处于选中或不确定状态时渲染。您可以直接为此元素设置样式，或将其作为包裹图标的容器使用，亦可同时进行。

tip

Built with Presence component - supports any animation techniques while maintaining access to presence emitted events.

Prop	Default	Type
`as`	`'span'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`forceMount`		`boolean` Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries.

Data Attribute	Value
`[data-state]`	`"checked" \| "unchecked" \| "indeterminate"`
`[data-disabled]`	禁用时出现

组根组件 (Group Root)

包裹 CheckboxRoot 以支持 modelValue 数组形式。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`defaultValue`		`AcceptableValue[]` The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
`dir`		`'ltr' \| 'rtl'` The direction of navigation between items.
`disabled`		`boolean` When `true`, prevents the user from interacting with the checkboxes
`loop`		`boolean` Whether keyboard navigation should loop around
`modelValue`		`AcceptableValue[]` The controlled value of the checkbox. Can be binded with v-model.
`name`		`string` The name of the field. Submitted with its owning form as part of a name/value pair.
`orientation`		`'vertical' \| 'horizontal'` The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down)
`required`		`boolean` When `true`, indicates that the user must set the value before the owning form can be submitted.
`rovingFocus`	`true`	`boolean` When `false`, navigating through the items using arrow keys will be disabled.

Emit	Payload
`update:modelValue`	`[value: AcceptableValue[]]` Event handler called when the value of the checkbox changes.

示例

不确定状态

通过控制其状态可将复选框设置为 indeterminate 不确定状态。

vue

<script setup>
import { Icon } from '@iconify/vue'
import { CheckboxIndicator, CheckboxRoot } from 'reka-ui'

const checked = ref('indeterminate')
</script>

<template>
  <CheckboxRoot v-model="checked">
    <CheckboxIndicator>
      <Icon
        v-if="checked === 'indeterminate'"
        icon="radix-icons:divider-horizontal"
      />
      <Icon
        v-if="checked"
        icon="radix-icons:check"
      />
    </CheckboxIndicator>
  </CheckboxRoot>

  <button
    type="button"
    @click="() => (checked === 'indeterminate' ? (checked = false) : (checked = 'indeterminate'))"
  >
    切换不确定状态
  </button>
</template>

无障碍访问

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

键盘交互

Key	Description
`空格键`	选中/取消选中复选框

复选框 ​

功能特性 ​

安装 ​

结构 ​

API 参考 ​

根组件 (Root) ​

指示器 (Indicator) ​

组根组件 (Group Root) ​

示例 ​

不确定状态 ​

无障碍访问 ​

键盘交互 ​

复选框