---
title: "Checkbox コンポーネント — zenit Zig UI"
description: "未選択・選択・不確定の状態を持つ独立したブール値の選択。状態、フォーカス、label のヒット領域、on_change が同じインタラクション境界を共有します。"
url: https://zenit.z.express/ja/components/checkbox
language: ja
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_ko: https://zenit.z.express/ko/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 してください。