---
title: "Checkbox 컴포넌트 — zenit Zig UI"
description: "선택 안 됨, 선택됨, 불확정 상태를 갖는 독립 불리언 선택.상태, 포커스, label 히트 영역, on_change가 하나의 상호작용 경계를 공유합니다."
url: https://zenit.z.express/ko/components/checkbox
language: ko
alternate_en: https://zenit.z.express/components/checkbox.md
alternate_zh: https://zenit.z.express/zh/components/checkbox.md
alternate_es: https://zenit.z.express/es/components/checkbox.md
alternate_ja: https://zenit.z.express/ja/components/checkbox.md
alternate_fr: https://zenit.z.express/fr/components/checkbox.md
alternate_de: https://zenit.z.express/de/components/checkbox.md
project: zenit v0.1.0-alpha (Zig 0.15.2, macOS)
source: https://github.com/version-next/zenit
---

# Checkbox

`ui.widgets.Checkbox`

선택 안 됨, 선택됨, 불확정 상태를 갖는 독립 불리언 선택.

[Video](https://zenit.z.express/media/stories/checkbox.mp4?v=079ee6a961)

**BEHAVIOR CONTRACT**

상태, 포커스, label 히트 영역, on\_change가 하나의 상호작용 경계를 공유합니다.

**RECORDED INTERACTION**

harness가 실제 checkbox를 클릭하면 상태 텍스트가 changed → checked로 바뀝니다.

`examples/storybook/stories.zig:184`

```zig
pub fn buildCheckbox(scope: *ui.Scope, cx: *ui.Cx) anyerror!*ui.Node {
    const a = cx.allocator;
    const c = try col(cx, 12);

    const status = try ui.text(cx, "changed → (none)", .{ .font_size = 13, .color = light.color.fg_secondary });
    status.meta.ownership.meta.test_id = "story.checkbox.status";

    const story = try cx.bindState(CheckboxStory, .{ .status = status });

    const unchecked = try ui.widgets.Checkbox(.{
        .label_text = "Unchecked",
        .initial_checked = false,
        .on_change = ui.Cx.boolHandlerFrom(CheckboxStory, story, CheckboxStory.onChange),
    }).mount(scope, cx);
    unchecked.meta.ownership.meta.test_id = "story.checkbox.box";
    try c.appendChild(a, unchecked);

    try c.appendChild(a, try ui.widgets.Checkbox(.{ .label_text = "Checked", .initial_checked = true }).mount(scope, cx));
    try c.appendChild(a, try ui.widgets.Checkbox(.{ .label_text = "Indeterminate", .indeterminate = true }).mount(scope, cx));
    try c.appendChild(a, try ui.widgets.Checkbox(.{ .label_text = "Disabled", .disabled = true }).mount(scope, cx));
    try c.appendChild(a, status);

    return c;
}
```

[GitHub에서 소스 보기examples/storybook/stories.zig:184](https://github.com/version-next/zenit/blob/HEAD/examples/storybook/stories.zig#L184)

Storybook에 있는 이 story의 원본 코드입니다(zenit 5f9add5+wip 2026-09-30). `W`는 `ui.widgets`이며, `col` / `row` / `label`은 Storybook 내부의 작은 레이아웃 헬퍼입니다.

### CheckboxProps

`ui.widgets.Checkbox`

[src/ui/components/checkbox/mod.zig:134](https://github.com/version-next/zenit/blob/HEAD/src/ui/components/checkbox/mod.zig#L134)

```zig
fn Checkbox(props: CheckboxProps) CheckboxBuilder
```

| 필드 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `initial_checked` | `bool` | `false` | 选中状态 初始勾选态。\*\*只在 mount 时读取一次\*\*，之后改无效（组件持有 自己的 CheckboxState）。需要外部驱动请用 mountResult 拿 state 后 调 setChecked，或用 ui.Show 重建。 |
| `indeterminate` | `bool` | `false` | 不确定状态 |
| `label_text` | `?[]const u8` | `null` | 标签 |
| `disabled` | `bool` | `false` | 禁用 |
| `on_change` | `?core.HandlerRef` | `null` | 变化回调。2026-07-31 并轨为 \`?core.HandlerRef\`。 需要拿到新值用 \`cx.boolHandlerFrom(State, ptr, method)\` 构造； 只关心"变了"用 \`cx.handlerFrom(...)\`。 |
| `state_id` | `?u64` | `null` | 状态 ID (用于 StateStore) |
| `check_icon_asset` | `?svg_assets.Asset` | `null` | Check icon SVG 资产 |

### \*Node

`ui.widgets.Checkbox`

mount는 `*Node`을(를) 직접 반환합니다. 부모 노드에 append하면 됩니다.