Checkbox

Checkbox는 여러 항목 중 복수 선택을 가능하게 하는 입력 컴포넌트입니다.

import { Checkbox } from '@vapor-ui/core';

export default function DefaultCheckbox() {
    return <Checkbox.Root />;
}

Property

Size

Checkbox 사이즈는 md, lg 로 제공합니다.

import { Checkbox } from '@vapor-ui/core';

export default function CheckboxSize() {
    return (
        <div className="flex items-center gap-4">
            <Checkbox.Root size="md" />
            <Checkbox.Root size="lg" />
        </div>
    );
}

Disabled

비활성화된 상태의 Checkbox입니다. 사용자가 상호작용할 수 없습니다.

import { Checkbox } from '@vapor-ui/core';

export default function CheckboxDisabled() {
    return (
        <div className="flex items-center gap-4">
            <Checkbox.Root disabled />
            <Checkbox.Root disabled checked />
        </div>
    );
}

Invalid

유효하지 않은 상태의 Checkbox입니다. 폼 검증 실패 시 사용됩니다.

import { Checkbox } from '@vapor-ui/core';

export default function CheckboxInvalid() {
    return (
        <div className="flex items-center gap-4">
            <Checkbox.Root invalid />
            <Checkbox.Root invalid checked />
        </div>
    );
}

Indeterminate

부분적으로 선택된 상태의 Checkbox입니다. 하위 항목 중 일부만 선택되었을 때 사용됩니다.

Select All Fruits

AppleBananaOrange

import { useState } from 'react';

import { Checkbox, Text } from '@vapor-ui/core';

export default function CheckboxIndeterminate() {
    const [checkedItems, setCheckedItems] = useState({
        apple: false,
        banana: false,
        orange: false,
    });

    const allChecked = Object.values(checkedItems).every(Boolean);
    const isIndeterminate = Object.values(checkedItems).some(Boolean) && !allChecked;

    const handleSelectAll = (checked: boolean) => {
        setCheckedItems({
            apple: checked,
            banana: checked,
            orange: checked,
        });
    };

    const handleItemChange = (item: keyof typeof checkedItems, checked: boolean) => {
        setCheckedItems((prev) => ({
            ...prev,
            [item]: checked,
        }));
    };

    return (
        <div className="space-y-3">
            <Text
                render={<label />}
                typography="body2"
                className="flex items-center gap-2.5 font-medium"
            >
                <Checkbox.Root
                    checked={allChecked}
                    indeterminate={isIndeterminate}
                    onCheckedChange={handleSelectAll}
                    className="flex items-center gap-3"
                />
                Select All Fruits
            </Text>
            <div className="ml-6 space-y-2">
                <Text
                    render={<label />}
                    typography="body2"
                    className="flex items-center gap-2.5 cursor-pointer"
                >
                    <Checkbox.Root
                        checked={checkedItems.apple}
                        onCheckedChange={(checked) => handleItemChange('apple', checked)}
                        className="flex items-center gap-3"
                    />
                    Apple
                </Text>

                <Text
                    render={<label />}
                    typography="body2"
                    className="flex items-center gap-2.5 cursor-pointer"
                >
                    <Checkbox.Root
                        checked={checkedItems.banana}
                        onCheckedChange={(checked) => handleItemChange('banana', checked)}
                        className="flex items-center gap-3"
                    />
                    Banana
                </Text>

                <Text
                    render={<label />}
                    typography="body2"
                    className="flex items-center gap-2.5 cursor-pointer"
                >
                    <Checkbox.Root
                        checked={checkedItems.orange}
                        onCheckedChange={(checked) => handleItemChange('orange', checked)}
                        className="flex items-center gap-3"
                    />
                    Orange
                </Text>
            </div>
        </div>
    );
}

Read Only

사용자는 체크박스 상태를 변경할 수 없지만, 현재 상태를 확인할 수 있도록 허용하는 상태입니다.

읽기 전용 (체크됨)읽기 전용 (체크 안됨)읽기 전용 (혼합 상태)

import { Checkbox, Flex } from '@vapor-ui/core';

export default function CheckboxReadOnly() {
    return (
        <Flex gap="$000" flexDirection="column">
            <label className="flex items-center gap-2">
                <Checkbox.Root readOnly defaultChecked>
                    <Checkbox.Indicator />
                </Checkbox.Root>
                읽기 전용 (체크됨)
            </label>
            <label className="flex items-center gap-2">
                <Checkbox.Root readOnly>
                    <Checkbox.Indicator />
                </Checkbox.Root>
                읽기 전용 (체크 안됨)
            </label>
            <label className="flex items-center gap-2">
                <Checkbox.Root readOnly indeterminate>
                    <Checkbox.Indicator />
                </Checkbox.Root>
                읽기 전용 (혼합 상태)
            </label>
        </Flex>
    );
}

Props Table

Checkbox.Root

Checkbox의 메인 컨테이너 컴포넌트입니다. Base UI의 Checkbox를 래핑하여 size, disabled, invalid 등의 속성을 제공하며, 체크, 미체크, 불확정 상태를 시각적으로 나타냅니다. 이 컴포넌트는 button 요소를 기반으로 합니다.

Prop	Default	Type
render?	button	ReactElementfunction
checked?	undefined	booleanindeterminate
defaultChecked?	undefined	booleanindeterminate
onCheckedChange?	undefined	function
disabled?	false	boolean
required?	undefined	boolean
name?	undefined	string
value?	on	string
size?	md	mdlg
invalid?	false	boolean
indeterminate?	false	boolean
readOnly?	false	boolean
className?	undefined	string
children?	undefined	ReactNode

Checkbox.Indicator

체크박스의 체크 상태를 시각적으로 표시하는 인디케이터 컴포넌트입니다. 체크됨/미체크됨/불확정 상태에 따라 적절한 아이콘을 표시합니다. Root 컴포넌트에서 자동으로 포함되므로 대부분의 경우 직접 사용할 필요가 없습니다. 이 컴포넌트는 div 요소를 기반으로 합니다.

Prop	Default	Type
render?	div	ReactElementfunction
forceMount?	undefined	boolean
className?	undefined	string

Checkbox

On this page