---
title: Segmented Control
url: "https://native-sdk.dev/docs/components/segmented-control"
docs_index: /llms.txt
lastUpdated: 2026-10-15
---

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

Use `segmented-control` for one item in an exclusive-choice control. Bind `selected` to the model and dispatch `on-press` to change it. Arrange several segments in a row. Each can include an `icon`. Use [tabs](/docs/components/tabs) for a tab-strip container with conditional panels.

## Markup

```html
<row gap="6">
  <segmented-control selected="{range == 'day'}" on-press="choose_day">Day</segmented-control>
  <segmented-control selected="{range == 'week'}" icon="settings" on-press="choose_week">Week</segmented-control>
  <segmented-control selected="{range == 'month'}" on-press="choose_month">Month</segmented-control>
</row>
```

`selected` is model-owned. Pressing a segment sends its message; the next view rebuild reflects the new selection. The segment itself is a text-bearing control, so it needs visible content or a `label` accessible name.

## Icons and sizes

The `icon` attribute uses the same closed vector-icon vocabulary as [button](/docs/components/button). It is drawn as part of the segment's own hit target and follows the segment's state tint. `size` selects the control size; `label` supplies an accessible name when the visible content is absent.

```html
<row gap="6">
  <segmented-control size="sm" selected="{view == 'list'}" icon="file-text" label="List" on-press="show_list" />
  <segmented-control size="sm" selected="{view == 'board'}" icon="settings" label="Board" on-press="show_board" />
</row>
```

## Programmatic construction (Zig)

In a Zig view, use the same retained widget kind directly with `canvas.Ui`:

```zig
ui.row(.{ .gap = 6 }, .{
    ui.el(.segmented_control, .{ .text = "Day", .selected = model.range == .day, .on_press = .choose_day }, .{}),
    ui.el(.segmented_control, .{ .text = "Week", .icon = "settings", .selected = model.range == .week, .on_press = .choose_week }, .{}),
    ui.el(.segmented_control, .{ .text = "Month", .selected = model.range == .month, .on_press = .choose_month }, .{}),
})
```

## Attributes

| Attribute        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`           | Text value for text-bearing elements; a literal or one \{binding}.                                                                                                                                                                                                                                                                                                                                                                              |
| `selected`       | Selected state; often a \{a == b} equality.                                                                                                                                                                                                                                                                                                                                                                                                     |
| `disabled`       | Disables the control; true/false or a \{binding}.                                                                                                                                                                                                                                                                                                                                                                                               |
| `size`           | Control size: default\|sm\|lg\|icon. On text, also the typography rungs heading\|display (themable token steps above title - a section heading, a hero stat); numeric sizes are not accepted - retheme the typography tokens instead.                                                                                                                                                                                                           |
| `icon`           | button, toggle-button, list-item, menu-item: vector icon drawn inline (buttons/toggle-buttons before the label, list/menu items as a leading slot): a built-in name (comptime-validated against canvas.icons.known\_icon\_names, e.g. save, plus, refresh-cw), an app-registered app:\<name>, or one \{binding} resolving to such a name. Icon-only buttons when the content is empty — add a label. One hit target, one enabled/disabled tint. |
| `icon-placement` | Icon slot side on label-bearing buttons/toggle-buttons: leading (default) draws the icon before the label, trailing after it — the next-page chevron. Icon-only buttons center the glyph regardless.                                                                                                                                                                                                                                            |
| `label`          | Accessible name; when set it REPLACES the element's text as the announced name - screen readers and automation snapshots see the label, never the text it shadows.                                                                                                                                                                                                                                                                              |
| `key`            | Sibling-scoped identity key; on for, names an item field.                                                                                                                                                                                                                                                                                                                                                                                       |
| `global-key`     | Parent-independent identity: ids survive reparenting between containers.                                                                                                                                                                                                                                                                                                                                                                        |
| `on-press`       | Dispatch a Msg on press: tag or tag:\{payload}. Legal on any element — a bound press handler makes it pressable, and presses on plain text/icons inside it fall through to it (dragging still selects text).                                                                                                                                                                                                                                    |
| `on-hold`        | Press-and-hold Msg: a pointer held \~350 ms dispatches it and the release then presses nothing; a quick click dispatches on-press as usual. A right/ctrl-click with no context menu on the route dispatches it immediately. Like on-press, binding it makes any element pressable.                                                                                                                                                              |

---

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)