Ordo UI
组件Controls

Checkbox

@mox-hub/ui 组件 · Controls · canonical

checkbox@mox-hub/uiControlscanonicalsrc/components/checkbox.tsx
变体演示checkbox

Props API

Prop类型默认值说明
className*string | ((state: CheckboxRootState) => string)——
onChange*(event: { target: { checked: boolean; }; }) => void——
onCheckedChange*(checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element; }) => void——

源码

packages/ui/src/components/checkbox.tsx
import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox"
import type React from "react"

import { cn } from "../lib/utils"

/*
 * coss ui Checkbox(base-ui 配方移植,registry @coss/checkbox)
 * 指示器内联 SVG 支持 indeterminate 态。
 */

// 兼容层:onChange({ target: { checked } })(历史 API)映射为 onCheckedChange
function Checkbox({
  className,
  onChange,
  onCheckedChange,
  ...props
}: CheckboxPrimitive.Root.Props & {
  onChange?: (event: { target: { checked: boolean } }) => void
}) {
  return (
    <CheckboxPrimitive.Root
      data-slot="checkbox"
      className={cn(
        "peer relative inline-flex size-4.5 shrink-0 items-center justify-center rounded-2xs border border-input bg-background not-dark:bg-clip-padding shadow-xs/5 outline-none ring-ring transition-shadow duration-fast before:pointer-events-none before:absolute before:inset-0 before:rounded-2xs-inset not-data-disabled:not-data-checked:not-aria-invalid:before:shadow-[0_1px_--theme(--color-black/4%)] after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:ring-offset-1 focus-visible:ring-offset-background aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 focus-visible:aria-invalid:border-destructive focus-visible:aria-invalid:ring-destructive/20 data-disabled:cursor-not-allowed data-disabled:opacity-50 group-data-[disabled]/field:opacity-50 sm:size-4 dark:not-data-checked:bg-input/32 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 dark:focus-visible:aria-invalid:ring-destructive/40 dark:not-data-disabled:not-data-checked:not-aria-invalid:before:shadow-[0_-1px_--theme(--color-white/6%)] [[data-disabled],[data-checked],[aria-invalid]]:shadow-none",
        className
      )}
      onCheckedChange={
        onCheckedChange ??
        (onChange ? (checked: boolean) => onChange({ target: { checked } }) : undefined)
      }
      {...props}
    >
      <CheckboxPrimitive.Indicator
        data-slot="checkbox-indicator"
        className="absolute -inset-px flex items-center justify-center rounded-2xs text-primary-foreground data-unchecked:hidden data-checked:bg-primary data-indeterminate:bg-primary data-indeterminate:text-primary-foreground"
        render={(
          props: React.ComponentProps<"span">,
          state: CheckboxPrimitive.Indicator.State
        ) => (
          <span {...props}>
            {state.indeterminate ? (
              <svg
                aria-hidden="true"
                className="size-3.5 sm:size-3"
                fill="none"
                height="24"
                stroke="currentColor"
                strokeLinecap="round"
                strokeLinejoin="round"
                strokeWidth="3"
                viewBox="0 0 24 24"
                width="24"
                xmlns="http://www.w3.org/2000/svg"
              >
                <path d="M5.252 12h13.496" />
              </svg>
            ) : (
              <svg
                aria-hidden="true"
                className="size-3.5 sm:size-3"
                fill="none"
                height="24"
                stroke="currentColor"
                strokeLinecap="round"
                strokeLinejoin="round"
                strokeWidth="3"
                viewBox="0 0 24 24"
                width="24"
                xmlns="http://www.w3.org/2000/svg"
              >
                <path d="M5.252 12.7 10.2 18.63 18.748 5.37" />
              </svg>
            )}
          </span>
        )}
      />
    </CheckboxPrimitive.Root>
  )
}

export { Checkbox }

可访问性与 RTL

  • 键盘:交互件保留:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。
  • RTL:间距、对齐与方向性图标使用逻辑属性 (ms-* /text-start /rtl:-scale-x-100);通过 ThemeProvider 或I18nProvider 的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。
  • 文案:优先用组件labels /translate /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

复选框,受控用 checked 与 onCheckedChange;与 Label 组合扩大点击区域。