Checkbox

설치

pnpm dlx ply-ui add checkbox icon

공통 설치 설정을 먼저 적용합니다.

사용법

각 항목을 독립적으로 선택할 때 사용합니다. Root를 label로 감싸고 선택 표시를 Indicator에 넣습니다. 여러 항목의 값을 함께 관리하려면 Checkbox Group을 사용합니다.

구성

구성 요소	역할
`Root`	체크 영역과 선택 상태입니다. `checked`, `onCheckedChange`, `indeterminate`, `disabled`, `size`를 지정합니다.
`Indicator`	선택 또는 일부 선택 상태의 표시를 담습니다.

선택된 초기값

defaultChecked로 초기 선택 상태를 지정합니다. 이후에는 사용자가 선택을 바꿀 수 있습니다.

비활성

disabled를 지정하면 선택 상태를 바꿀 수 없습니다.

일부 선택

indeterminate로 하위 항목 중 일부가 선택된 상태를 표시합니다. 하위 항목과의 상태 계산은 별도로 연결합니다.

크기

size의 기본값은 sm입니다. 현재 md와 lg는 모두 24px로 표시됩니다.

속성

이 프로젝트에서 추가하거나 제한한 속성입니다.

Root

속성

타입

구현 코드

components/ui/checkbox.tsx

checkbox.tsx

"use client";

import type { ComponentProps } from "react";
import { Checkbox as Primitive } from "@base-ui/react/checkbox";
import { withClassName } from "../../lib/cx";
import "./checkbox.css";

// 동작과 접근성은 Base UI가 담당합니다. 이 파일은 스타일 연결만 담당합니다.
export type CheckboxRootProps = ComponentProps<typeof Primitive.Root> & {
  /** 체크 영역 크기입니다. @defaultValue "sm" */
  size?: "xs" | "sm" | "md" | "lg";
};
function CheckboxRoot({ size = "sm", className, ...props }: CheckboxRootProps) {
  return (
    <Primitive.Root
      {...props}
      data-size={size}
      className={withClassName("rbx-checkbox", className)}
    />
  );
}

function CheckboxIndicator({
  className,
  ...props
}: ComponentProps<typeof Primitive.Indicator>) {
  return (
    <Primitive.Indicator
      {...props}
      className={withClassName("rbx-checkbox-indicator", className)}
    />
  );
}

// Root/Portal 등 스타일 없는 파트와 제네릭 API는 원본을 그대로 보존합니다.
export const Checkbox = {
  ...Primitive,
  Root: CheckboxRoot,
  Indicator: CheckboxIndicator,
};

components/ui/checkbox.css

checkbox.css

/* Checkbox: 공통 구조는 theme.css, 컴포넌트 전용 조정은 아래에 작성합니다. */
.rbx-checkbox {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: 0;
  width: 20px;
  height: 20px;
  flex-shrink: 0;
  border: 1px solid var(--rbx-color-stroke-contrast-alpha);
  border-radius: var(--rbx-radius-small);
  background: transparent;
  color: var(--rbx-inverse-content-emphasis);
  cursor: pointer;
}
.rbx-checkbox[data-checked],
.rbx-checkbox[data-indeterminate] {
  background: var(--rbx-color-system-contrast);
  border-color: transparent;
}
.rbx-checkbox-indicator {
  display: flex;
  align-items: center;
  justify-content: center;
  width: 100%;
  height: 100%;
}
.rbx-checkbox-indicator > .rbx-icon {
  width: 100%;
  height: 100%;
}
/* 원본 체크 glyph의 넓은 내부 여백을 보정합니다. 바깥 박스 크기는 유지합니다. */
.rbx-checkbox-indicator > [data-icon="icon-filled-check"] {
  mask-size: 150%;
}

.rbx-checkbox[data-size="xs"] {
  width: 16px;
  height: 16px;
}
.rbx-checkbox:is([data-size="md"], [data-size="lg"]) {
  width: 24px;
  height: 24px;
}

목차