---
title: Toggle
url: "https://native-sdk.dev/docs/components/toggle"
docs_index: /llms.txt
lastUpdated: 2026-10-16
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

Use `toggle` for a button that stays pressed. Bind `checked` and handle `on-toggle`. For grouped choices, place `toggle-button` elements in a `toggle-group`, bind each item’s `selected` state, and handle its `on-toggle`. The model determines whether the group allows one or several selections. Use [switch](/docs/components/switch) for a sliding on/off control.

## Markup

```html
<toggle-group>
  <toggle-button selected="{align == 'left'}" on-toggle="align_left">Left</toggle-button>
  <toggle-button selected="{align == 'center'}" on-toggle="align_center">Center</toggle-button>
  <toggle-button selected="{align == 'right'}" on-toggle="align_right">Right</toggle-button>
</toggle-group>
```

## Toggle

The standalone `toggle` element carries its own label; bind `checked` and handle `on-toggle` exactly like a [checkbox](/docs/components/checkbox).

```html
<row gap="12" cross="center">
  <toggle checked="{bold}" on-toggle="toggle_bold">Bold</toggle>
  <toggle checked="{italic}" on-toggle="toggle_italic">Italic</toggle>
  <toggle disabled="true" on-toggle="toggle_underline">Underline</toggle>
</row>
```

## Programmatic construction (Zig)

In a Zig view, the `canvas.Ui` builder constructs the same tree programmatically:

```zig
ui.el(.toggle_group, .{}, .{
    ui.el(.toggle_button, .{ .text = "Left", .selected = model.align == .left, .on_toggle = .align_left }, .{}),
    ui.el(.toggle_button, .{ .text = "Center", .selected = model.align == .center, .on_toggle = .align_center }, .{}),
    ui.el(.toggle_button, .{ .text = "Right", .selected = model.align == .right, .on_toggle = .align_right }, .{}),
})
```

The standalone toggle:

```zig
ui.row(.{ .gap = 12, .cross = .center }, .{
    ui.el(.toggle, .{ .text = "Bold", .checked = model.bold, .on_toggle = .toggle_bold }, .{}),
    ui.el(.toggle, .{ .text = "Italic", .checked = model.italic, .on_toggle = .toggle_italic }, .{}),
    ui.el(.toggle, .{ .text = "Underline", .disabled = true, .on_toggle = .toggle_underline }, .{}),
})
```

## Attributes

| Attribute   | Description                                                                                                                          |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `text`      | Text value for text-bearing elements; a literal or one \{binding}.                                                                   |
| `checked`   | Checked state for checkbox/toggle; true/false or a \{binding}.                                                                       |
| `selected`  | Selected state; often a \{a == b} equality.                                                                                          |
| `disabled`  | Disables the control; true/false or a \{binding}.                                                                                    |
| `on-toggle` | Dispatch a Msg on toggle: tag or tag:\{payload}. Hit-target elements only (checkbox, toggle, toggle-button, switch, accordion, ...). |

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)