Component

Checkbox

독립적인 예/아니오 선택이나 여러 항목의 복수 선택을 표현합니다.

Playground

옵션을 조절하며 화면과 사용 코드를 함께 확인하세요.

PC 1280px

Controls

input 옆 레이블

같은 size의 입력 필드에 맞춘 표시·레이블 크기

선택 상태: false, true, indeterminate

비활성

Code

import { type ControlSize, Checkbox } from '@amineslab/ui'

import { useState } from 'react'

const controlSizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const satisfies readonly ControlSize[];

const sizes = controlSizes;

type Size = (typeof sizes)[number];

type MarkSize = Size;

function CheckboxPreview({ initialChecked, ...props }: {
    initialChecked: string;
    disabled: boolean;
    label?: string;
    size: MarkSize;
}) {
    const [checked, setChecked] = useState<boolean | 'indeterminate'>(initialChecked === 'indeterminate' ? 'indeterminate' : initialChecked === 'true');
    return <Checkbox {...props} checked={checked} onCheckedChange={setChecked}/>;
}

export default function ExamplePreview() {
  return ((<CheckboxPreview initialChecked={"true"} disabled={false} key={"true"} label={"알림 메일 받기"} size={"md"}/>))
}

Props

@amineslab/ui에서 Checkbox를 가져옵니다.

import { Checkbox } from '@amineslab/ui'

`Checkbox`

HTML <button> 요소의 표준 속성을 그대로 받습니다.

Name	Type	Default	Description
`checked`	`boolean \| 'indeterminate'`	-	외부에서 제어하는 선택 상태입니다.
`defaultChecked`	`boolean \| 'indeterminate'`	`false`	내부 상태로 관리할 때의 초기값입니다.
`onCheckedChange`	`(checked: boolean \| 'indeterminate') => void`	-	상태가 바뀔 때 호출합니다.
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	같은 size의 입력 필드와 비례하는 표시·레이블 크기입니다. 모바일 표시는 4px 확대됩니다.
`indeterminate`	`boolean`	`false`	기존 부분 선택 별칭입니다. checked="indeterminate" 사용을 권장합니다.
`label`	`ReactNode`	-	checkbox 옆에 표시할 레이블입니다.

Examples

자주 쓰는 조합을 살펴보고, 필요한 예시의 코드를 펼쳐 확인하세요.

Group

부분 선택은 checked="indeterminate"로 표시합니다. checked는 onCheckedChange로 갱신하고, defaultChecked는 내부에서 상태를 관리할 때 최초 값만 지정합니다.

모든 알림댓글멘션

import { type ComponentPropsWithoutRef } from 'react'

import { cn } from '@amineslab/ui/utils'

import { Checkbox } from '@amineslab/ui'

function ExampleStack({ className, compact = false, fullWidth = false, ...props }: ComponentPropsWithoutRef<'div'> & {
    compact?: boolean;
    fullWidth?: boolean;
}) {
    return (<div {...props} className={cn('grid', compact ? 'w-auto gap-2' : fullWidth ? 'w-full gap-4' : 'w-full max-w-[360px] gap-3', className)}/>);
}

export default function ExamplePreview() {
  return ((<ExampleStack compact>
          <Checkbox checked="indeterminate" label="모든 알림"/>
          <Checkbox defaultChecked label="댓글"/>
          <Checkbox label="멘션"/>
        </ExampleStack>))
}

Disabled

비활성비활성 선택됨

import { type ComponentPropsWithoutRef } from 'react'

import { cn } from '@amineslab/ui/utils'

import { Checkbox } from '@amineslab/ui'

function ExampleStack({ className, compact = false, fullWidth = false, ...props }: ComponentPropsWithoutRef<'div'> & {
    compact?: boolean;
    fullWidth?: boolean;
}) {
    return (<div {...props} className={cn('grid', compact ? 'w-auto gap-2' : fullWidth ? 'w-full gap-4' : 'w-full max-w-[360px] gap-3', className)}/>);
}

export default function ExamplePreview() {
  return ((<ExampleStack compact>
          <Checkbox disabled label="비활성"/>
          <Checkbox defaultChecked disabled label="비활성 선택됨"/>
        </ExampleStack>))
}

CheckboxField로 사용하기

CheckboxField는 기본 입력에 label·required·description·error를 함께 제공합니다. FormStack 안에 직접 넣으며 FormField로 다시 감싸지 않습니다.

약관 동의

라벨·설명·필수 표시를 Field가 함께 처리합니다.

import { useState } from 'react'

import { CheckboxField } from '@amineslab/ui'

const fieldDescription = '라벨·설명·필수 표시를 Field가 함께 처리합니다.';

function CheckboxFieldExample() {
    const [value, setValue] = useState(false);
    return (<CheckboxField label="약관 동의" description={fieldDescription} required value={value} onValueChange={setValue}/>);
}

export default function ExamplePreview() {
  return (<CheckboxFieldExample />)
}

사용 기준

권장하는 사용

레이블을 클릭해도 상태가 바뀌게 연결합니다.

피해야 할 사용

겉모양만으로 사용을 결정하지 마세요.
의미와 키보드 동작, 모바일에서의 흐름을 함께 확인하세요.

접근성

화면에 맞는 이름을 제공하고, 키보드만으로 작업을 마칠 수 있는지 확인하세요.

Space: checked 상태 전환