---
title: "Checkbox-Komponente — zenit Zig UI"
description: "Ein unabhängiger Boolean mit den Zuständen nicht markiert, markiert und unbestimmt. Zustand, Fokus, die Klickfläche des Labels und on_change teilen sich eine…"
url: https://zenit.z.express/de/components/checkbox
language: de
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_ko: https://zenit.z.express/ko/components/checkbox.md
alternate_fr: https://zenit.z.express/fr/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`

Ein unabhängiger Boolean mit den Zuständen nicht markiert, markiert und unbestimmt.

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

**BEHAVIOR CONTRACT**

Zustand, Fokus, die Klickfläche des Labels und on\_change teilen sich eine Interaktionsgrenze.

**RECORDED INTERACTION**

Der Harness klickt die echte Checkbox; der Status zeigt 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;
}
```

[Quellcode auf GitHub ansehenexamples/storybook/stories.zig:184](https://github.com/version-next/zenit/blob/HEAD/examples/storybook/stories.zig#L184)

Der unveränderte Quellcode der Story aus dem Storybook (zenit 5f9add5+wip 2026-09-30). `W` steht für `ui.widgets`; `col` / `row` / `label` sind kleine Layout-Helfer des Storybooks.

### 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
```

| Feld | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `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 gibt `*Node` direkt zurück – hängen Sie es an einen Elternknoten an.