Checkbox 复选框组件 #

基本用法 #

jsx
import { Checkbox } from '@chakra-ui/react'

function Example() {
  return <Checkbox>默认复选框</Checkbox>
}

复选框状态 #

选中状态 #

jsx
<Checkbox defaultIsChecked>默认选中</Checkbox>

禁用状态 #

jsx
<Checkbox isDisabled>禁用复选框</Checkbox>
<Checkbox isDisabled defaultIsChecked>禁用且选中</Checkbox>

只读状态 #

jsx
<Checkbox isReadOnly>只读复选框</Checkbox>

无效状态 #

jsx
<Checkbox isInvalid>无效复选框</Checkbox>

复选框尺寸 #

jsx
<Checkbox size="sm">小复选框</Checkbox>
<Checkbox size="md">中等复选框(默认)</Checkbox>
<Checkbox size="lg">大复选框</Checkbox>

复选框颜色 #

jsx
<Checkbox colorScheme="red">红色</Checkbox>
<Checkbox colorScheme="green">绿色</Checkbox>
<Checkbox colorScheme="blue">蓝色</Checkbox>
<Checkbox colorScheme="orange">橙色</Checkbox>
<Checkbox colorScheme="purple">紫色</Checkbox>

受控复选框 #

jsx
function ControlledCheckbox() {
  const [isChecked, setIsChecked] = useState(false)

  return (
    <Checkbox
      isChecked={isChecked}
      onChange={(e) => setIsChecked(e.target.checked)}
    >
      受控复选框
    </Checkbox>
  )
}

CheckboxGroup 复选框组 #

jsx
import { CheckboxGroup } from '@chakra-ui/react'

function CheckboxGroupExample() {
  const [value, setValue] = useState(['apple'])

  return (
    <CheckboxGroup
      value={value}
      onChange={setValue}
      colorScheme="green"
    >
      <VStack align="start">
        <Checkbox value="apple">苹果</Checkbox>
        <Checkbox value="banana">香蕉</Checkbox>
        <Checkbox value="orange">橙子</Checkbox>
      </VStack>
    </CheckboxGroup>
  )
}

配合 FormControl #

jsx
import { FormControl, FormLabel, FormErrorMessage } from '@chakra-ui/react'

function FormCheckbox() {
  const [agreed, setAgreed] = useState(false)
  const isError = !agreed

  return (
    <FormControl isInvalid={isError}>
      <Checkbox
        isChecked={agreed}
        onChange={(e) => setAgreed(e.target.checked)}
      >
        我同意用户协议和隐私政策
      </Checkbox>
      {isError && (
        <FormErrorMessage>请先同意用户协议</FormErrorMessage>
      )}
    </FormControl>
  )
}

自定义图标 #

jsx
<Checkbox icon={<MinusIcon />} iconColor="blue.500">
  自定义图标
</Checkbox>

实用示例 #

用户偏好设置 #

jsx
function UserPreferences() {
  const [preferences, setPreferences] = useState({
    email: true,
    sms: false,
    push: true,
  })

  return (
    <VStack align="start" spacing={4}>
      <Heading size="sm">通知设置</Heading>
      <Checkbox
        isChecked={preferences.email}
        onChange={(e) => setPreferences({
          ...preferences,
          email: e.target.checked
        })}
      >
        邮件通知
      </Checkbox>
      <Checkbox
        isChecked={preferences.sms}
        onChange={(e) => setPreferences({
          ...preferences,
          sms: e.target.checked
        })}
      >
        短信通知
      </Checkbox>
      <Checkbox
        isChecked={preferences.push}
        onChange={(e) => setPreferences({
          ...preferences,
          push: e.target.checked
        })}
      >
        推送通知
      </Checkbox>
    </VStack>
  )
}

权限选择 #

jsx
function PermissionSelect() {
  const [permissions, setPermissions] = useState(['read'])

  return (
    <Box>
      <Text fontWeight="medium" mb={2}>权限设置</Text>
      <CheckboxGroup
        value={permissions}
        onChange={setPermissions}
      >
        <VStack align="start" spacing={2}>
          <Checkbox value="read">读取</Checkbox>
          <Checkbox value="write">写入</Checkbox>
          <Checkbox value="delete">删除</Checkbox>
          <Checkbox value="admin">管理</Checkbox>
        </VStack>
      </CheckboxGroup>
    </Box>
  )
}

全选功能 #

jsx
function SelectAll() {
  const allItems = ['item1', 'item2', 'item3', 'item4']
  const [selected, setSelected] = useState([])

  const allChecked = selected.length === allItems.length
  const isIndeterminate = selected.length > 0 && selected.length < allItems.length

  return (
    <Box>
      <Checkbox
        isChecked={allChecked}
        isIndeterminate={isIndeterminate}
        onChange={(e) => {
          if (e.target.checked) {
            setSelected(allItems)
          } else {
            setSelected([])
          }
        }}
      >
        全选
      </Checkbox>
      <Divider my={2} />
      <CheckboxGroup value={selected} onChange={setSelected}>
        <VStack align="start">
          {allItems.map((item) => (
            <Checkbox key={item} value={item}>{item}</Checkbox>
          ))}
        </VStack>
      </CheckboxGroup>
    </Box>
  )
}

服务条款同意 #

jsx
function TermsAgreement() {
  const [agreements, setAgreements] = useState([])

  return (
    <VStack align="start" spacing={4}>
      <CheckboxGroup value={agreements} onChange={setAgreements}>
        <VStack align="start">
          <Checkbox value="terms">
            我已阅读并同意《用户服务协议》
          </Checkbox>
          <Checkbox value="privacy">
            我已阅读并同意《隐私政策》
          </Checkbox>
          <Checkbox value="marketing">
            我同意接收营销推广信息(可选)
          </Checkbox>
        </VStack>
      </CheckboxGroup>
      <Button
        colorScheme="blue"
        isDisabled={!agreements.includes('terms') || !agreements.includes('privacy')}
      >
        继续
      </Button>
    </VStack>
  )
}

Checkbox 属性速查表 #

属性 说明
isChecked 是否选中 true, false
defaultIsChecked 默认选中 true, false
isDisabled 禁用 true, false
isInvalid 无效 true, false
isReadOnly 只读 true, false
isIndeterminate 不确定状态 true, false
size 尺寸 sm, md, lg
colorScheme 颜色方案 blue, green, red…
icon 自定义图标 React 元素

下一步 #

现在你已经掌握了 Checkbox 组件,接下来学习 Radio 单选框,了解如何使用单选按钮组件!

最后更新:2026-03-28