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

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

Use `pagination` to arrange page-navigation buttons horizontally. The model owns the current page, and each button dispatches an `on-press` message. Use `ghost` for page numbers and `outline` with `selected` for the current page. Previous and next buttons can use `chevron-left` and `chevron-right`; an `ellipsis` icon indicates omitted pages.

## Markup

```html
<pagination>
  <button variant="ghost" icon="chevron-left" on-press="prev_page">Previous</button>
  <for each="pages" as="p" key="number">
    <button variant="{p.variant}" selected="{p.number == page}" on-press="open_page:{p.number}">{p.label}</button>
  </for>
  <icon name="ellipsis" />
  <button variant="ghost" icon="chevron-right" icon-placement="trailing" on-press="next_page">Next</button>
</pagination>
```

Use `outline` to distinguish the current page visually and `selected` to expose its state to accessibility tools. In a `for` loop, a row field or function can return `outline` or `ghost` for the variant.

## Programmatic construction (Zig)

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

```zig
ui.el(.pagination, .{}, .{
    ui.button(.{ .variant = .ghost, .icon = "chevron-left", .on_press = .prev_page }, "Previous"),
    ui.button(.{ .variant = .outline, .selected = model.page == 1, .on_press = .{ .open_page = 1 } }, "1"),
    ui.button(.{ .variant = .ghost, .on_press = .{ .open_page = 2 } }, "2"),
    ui.button(.{ .variant = .ghost, .on_press = .{ .open_page = 3 } }, "3"),
    ui.icon(.{}, "ellipsis"),
    ui.button(.{ .variant = .ghost, .icon = "chevron-right", .icon_placement = .trailing, .on_press = .next_page }, "Next"),
})
```

## Attributes

| Attribute        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `selected`       | Selected state; often a \{a == b} equality.                                                                                                                                                                                                                                                                                                                                                                                                     |
| `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).                                                                                                                                                                                                                                    |
| `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.                                                                                                                                                                                                                                            |

---

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)