# Core widgets

> API reference for Pyzed's native widgets: layout, text, controls, the code editor, SVG and icons, all rendered in Rust by Iced.

Source: https://albakore.github.io/pyzed/reference/widgets/

<!-- Generated by docs/scripts/gen_api.py. Edit docs/scripts/api_docs_en.py. -->

The core widgets are implemented in Rust and imported from `pyzed`. They are the
building blocks of the [components](https://albakore.github.io/pyzed/components/overview/).
See the [layout](https://albakore.github.io/pyzed/guides/layout/) guide for sizes, padding and colors.

## Widget

### `Widget`

An immutable node of the UI tree, implemented in Rust. Returned by every widget and component function. Wherever a child is expected you can also pass a string or a number (converted to `text`) or `None` (ignored).

Every widget has `widget.on(...)` (see [Events](https://albakore.github.io/pyzed/guides/events/)) and `widget.style(*styles, **props)`, which styles it like CSS: background, borders, radius, shadow, padding, margin, size and the typography of every text inside. `widget.style_props()` returns what was set. `widget.classes(*names, id=None)` applies the matching rules of `pz.stylesheet`, like HTML's `class` and `id`. See [Styles](https://albakore.github.io/pyzed/theming/styles/).

`widget.animate(*animations, **options)` plays presets or keyframe animations (on mount, hover, press, focus, click or while `active`) and `widget.transition(**props)` animates property changes like a CSS transition. See [Animation](https://albakore.github.io/pyzed/animation/).

## Layout

### `column`

```python
column(
    children=None,
    *,
    spacing=0.0,
    padding=None,
    width=None,
    height=None,
    align=None,
    max_width=None,
    clip=False,
)
```

Stacks its children vertically.

| Parameter | Description |
| --- | --- |
| `children` | List of children. Nested lists are flattened and `None` and `False` are ignored, so you can write `cond and widget`. |
| `spacing` | Space between children, in pixels. |
| `padding` | Inner padding: `8`, `(vertical, horizontal)` or `(top, right, bottom, left)`. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `align` | Alignment of the children on the cross axis: `"start"`, `"center"` or `"end"`. |
| `max_width` | Maximum width in pixels. |
| `clip` | Clips content that overflows the bounds. |

```python
pz.column([pz.text("One"), pz.text("Two")], spacing=8, padding=16)
```

### `row`

```python
row(
    children=None,
    *,
    spacing=0.0,
    padding=None,
    width=None,
    height=None,
    align=None,
    clip=False,
    wrap=False,
    line_spacing=None,
)
```

Lays out its children horizontally.

| Parameter | Description |
| --- | --- |
| `children` | List of children. Nested lists are flattened and `None` and `False` are ignored, so you can write `cond and widget`. |
| `spacing` | Space between children, in pixels. |
| `padding` | Inner padding: `8`, `(vertical, horizontal)` or `(top, right, bottom, left)`. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `align` | Alignment of the children on the cross axis: `"start"`, `"center"` or `"end"`. |
| `clip` | Clips content that overflows the bounds. |
| `wrap` | Line wrapping / moves children to a new row when they don't fit. |
| `line_spacing` | Space between rows when `wrap=True`. |

```python
pz.row([ui.label("Name"), pz.hspace(), ui.button("OK", "ok")], align="center")
```

### `container`

```python
container(
    content=None,
    *,
    padding=None,
    width=None,
    height=None,
    max_width=None,
    max_height=None,
    align_x=None,
    align_y=None,
    center=False,
    bg=None,
    color=None,
    border_color=None,
    border_width=0.0,
    radius=None,
    shadow=None,
    clip=False,
    gradient=None,
)
```

Wraps a child to give it size, alignment, background, border, radius and shadow.

| Parameter | Description |
| --- | --- |
| `content` | The child (or `None` for an empty box, handy as a colored rectangle). |
| `padding` | Inner padding: `8`, `(vertical, horizontal)` or `(top, right, bottom, left)`. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `max_width` | Maximum width in pixels. |
| `max_height` | Maximum height in pixels. |
| `align_x` | Horizontal alignment: `"start"`/`"left"`, `"center"`, `"end"`/`"right"`. |
| `align_y` | Vertical alignment: `"start"`/`"top"`, `"center"`, `"end"`/`"bottom"`. |
| `center` | Centers the content on both axes and fills all the space. |
| `bg` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `color` | Text or icon color. |
| `border_color` | Border color. |
| `border_width` | Border width in pixels. |
| `radius` | Corner radius: a number or `(top_left, top_right, bottom_right, bottom_left)`. |
| `shadow` | Shadow: `(color, (dx, dy), blur)`. |
| `clip` | Clips content that overflows the bounds. |
| `gradient` | Linear background gradient: `(angle, [colors])` or `(angle, [(position, color), ...])`. |

### `center`

```python
center(content, **kwargs)
```

Centers `content` in all the available space. Equivalent to `container(content, center=True)`.

| Parameter | Description |
| --- | --- |
| `content` | Content: a `Widget`, a string or a number (converted to text). |
| `kwargs` | Any `container` parameter. |

### `scrollable`

```python
scrollable(
    content,
    *,
    direction='vertical',
    width=None,
    height=None,
    padding=None,
    id=None,
    anchor_bottom=False,
    rail=None,
    scroller=None,
    scroller_hover=None,
    scrollbar_width=8.0,
    scroller_width=None,
    margin=0.0,
    on_scroll=None,
)
```

Makes its content scrollable.

| Parameter | Description |
| --- | --- |
| `content` | Content: a `Widget`, a string or a number (converted to text). |
| `direction` | `"vertical"`, `"horizontal"` or `"both"`. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `padding` | Inner padding: `8`, `(vertical, horizontal)` or `(top, right, bottom, left)`. |
| `id` | Stable identifier used to focus or scroll it with a `Command`. |
| `anchor_bottom` | Keeps the scroll pinned to the end (logs, terminals, chats). |
| `rail` | Scrollbar rail color. |
| `scroller` | Scroller color. |
| `scroller_hover` | Scroller color on hover. |
| `scrollbar_width` | Scrollbar width. |
| `scroller_width` | Scroller width (defaults to the scrollbar's). |
| `margin` | Margin between the scrollbar and the content. |
| `on_scroll` | Callable that receives a dict with `x`, `y`, `relative_x`, `relative_y`, `width`, `height`, `content_width` and `content_height`. |

### `stack`

```python
stack(children=None, *, width=None, height=None)
```

Layers its children on top of each other, the last one on top. The basis for layers, modals and notifications.

| Parameter | Description |
| --- | --- |
| `children` | List of children. Nested lists are flattened and `None` and `False` are ignored, so you can write `cond and widget`. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |

### `space`

```python
space(width=None, height=None)
```

Empty space of a given size.

| Parameter | Description |
| --- | --- |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |

### `hspace`

```python
hspace(width='fill')
```

Flexible horizontal gap: pushes the siblings in a row towards the edges.

| Parameter | Description |
| --- | --- |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |

### `vspace`

```python
vspace(height='fill')
```

Flexible vertical gap: pushes the siblings in a column towards the edges.

| Parameter | Description |
| --- | --- |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |

### `rule`

```python
rule(*, vertical=False, thickness=1.0, color=None)
```

A horizontal (or vertical) divider line.

| Parameter | Description |
| --- | --- |
| `vertical` | Vertical line instead of horizontal. |
| `thickness` | Thickness in pixels. |
| `color` | Text or icon color. |

A horizontal rule fills the full width. Inside a column that should shrink, set `width="shrink"` on the column.

### `grid`

```python
grid(
    children=None,
    *,
    columns=None,
    rows=None,
    max_width=None,
    spacing=0.0,
    row_spacing=None,
    height=None,
    aspect_ratio=None,
    width=None,
    padding=None,
    align_x=None,
    align_y=None,
)
```

Lays out its children in a grid. With `columns=3` the columns are equal (or `max_width` fits as many as possible). With track lists (`columns=[200, "1fr", "auto"]`, `rows=...`) it works like a CSS grid: numbers are pixels, `"auto"` fits the content and `"<n>fr"` shares the space left. Wrap children in `pz.cell` to place them and make them span; the rest fill the free cells row by row. See [Layout](https://albakore.github.io/pyzed/guides/layout/#grids).

| Parameter | Description |
| --- | --- |
| `children` | List of children. Nested lists are flattened and `None` and `False` are ignored, so you can write `cond and widget`. |
| `columns` | Number of equal columns, or tracks: a list (`[200, "1fr", "auto"]`) or a string (`"200 1fr auto"`). |
| `rows` | Row tracks, like `columns`. Rows beyond the list are `"auto"`. |
| `max_width` | Fits as many columns of at most this width as possible (`columns=<int>` only). |
| `spacing` | Space between cells. |
| `row_spacing` | Space between rows, if different. |
| `height` | With `columns=<int>`: height of each row. With tracks: the grid's height. |
| `aspect_ratio` | Keeps cells at this width/height ratio (`columns=<int>` only). |
| `width` | With `columns=<int>`: pixels. With tracks: the grid's width (default `"fill"`). |
| `padding` | Space around the cells. |
| `align_x` | Horizontal alignment of items in their cells: `"start"`, `"center"`, `"end"`. |
| `align_y` | Vertical alignment of items in their cells. |

```python
pz.grid([pz.cell(header, column=0, row=0, column_span=2), sidebar, content],
        columns=[200, "1fr"], rows=[48, "1fr"], spacing=8, height="fill")
```

### `cell`

```python
cell(
    content,
    *,
    column=None,
    row=None,
    column_span=1,
    row_span=1,
    align_x=None,
    align_y=None,
)
```

Places a child in a track grid: its column and row (from 0) and how many it spans. Children without a cell fill the free cells row by row. Outside a grid it is just the child.

| Parameter | Description |
| --- | --- |
| `content` | The widget. |
| `column` | Column index (from 0). |
| `row` | Row index (from 0). |
| `column_span` | Columns it covers. |
| `row_span` | Rows it covers. |
| `align_x` | Horizontal alignment in the cell. |
| `align_y` | Vertical alignment in the cell. |

```python
pz.cell(ui.button("Save"), column=2, row=3, align_x="end")
```

### `box`

```python
box(
    *children,
    display='block',
    direction='row',
    gap=0,
    wrap=False,
    justify='start',
    align=None,
    columns=None,
    rows=None,
    overflow='visible',
    class_=None,
    id=None,
    style=None,
    **props,
)
```

A container for anything, like an HTML `div`: it lays out its children (`display` `"block"`, `"flex"`, `"grid"` or `"stack"`) and takes every style property, stylesheet classes and an id. Children styled with `position="absolute"` are placed by `top`/`right`/`bottom`/`left` above the rest. See [Boxes](https://albakore.github.io/pyzed/guides/layout/#boxes).

| Parameter | Description |
| --- | --- |
| `children` | The widgets, one by one or in lists. `None` and `False` are skipped. |
| `display` | `"block"` (one under another, as wide as the box), `"flex"`, `"grid"` or `"stack"`. |
| `direction` | With `display="flex"`: `"row"` or `"column"`. |
| `gap` | Space between children. |
| `wrap` | With `"flex"` rows: wraps onto new lines. |
| `justify` | With `"flex"`: `"start"`, `"center"`, `"end"`, `"between"`, `"around"` or `"evenly"`. |
| `align` | `"start"`, `"center"`, `"end"` or `"stretch"` (the default for `"block"`). |
| `columns` | With `"grid"`: a count of equal columns or tracks (`"200 1fr auto"`). |
| `rows` | With `"grid"`: row tracks. |
| `overflow` | `"visible"`, `"hidden"`, `"scroll"`, `"scroll_x"` or `"scroll_y"`. |
| `class_` | Stylesheet classes (`"card selected"` or a list). |
| `id` | The id for `#id` rules. |
| `style` | A `pz.Style`, dict or style name. |
| `props` | Style properties, on top of the rest. |

```python
pz.box(title, pz.box(cancel, save, display="flex", justify="end", gap=8), class_="card", gap=12)
```

### `flex`

```python
flex(
    children=(),
    *,
    direction='row',
    justify='start',
    align='start',
    gap=0,
    wrap=False,
    padding=None,
    width=None,
    height=None,
)
```

Lays children out along one axis, like CSS flexbox, with `justify` on the main axis and `align` on the cross axis. Use `pz.flex_item` to make a child grow or give it a fixed size.

| Parameter | Description |
| --- | --- |
| `children` | The widgets, or `pz.flex_item(...)` for children with their own sizing. |
| `direction` | `"row"` or `"column"`. |
| `justify` | `"start"`, `"center"`, `"end"`, `"between"`, `"around"` or `"evenly"`. No effect when a child grows. |
| `align` | Cross-axis alignment: `"start"`, `"center"` or `"end"`. |
| `gap` | Space between children. |
| `wrap` | Wraps onto new lines (rows with `justify="start"` only). |
| `padding` | Space around the children. |
| `width` | Width. |
| `height` | Height. |

```python
pz.flex([logo, title, pz.flex_item(search, grow=1), avatar], justify="between", align="center", gap=8)
```

### `flex_item`

```python
flex_item(content, *, grow=1, basis=None, align=None)
```

Sizes a child of `pz.flex`.

| Parameter | Description |
| --- | --- |
| `content` | The widget. |
| `grow` | Share of the free space on the main axis (`0` keeps its natural size). |
| `basis` | A fixed main size in pixels, instead of growing. |
| `align` | Cross-axis alignment for this child. |

### `anchor`

```python
anchor(
    content,
    *,
    x=0,
    y=0,
    width=100,
    height=28,
    anchor='top_left',
    min_width=0,
    min_height=0,
    max_width=0,
    max_height=0,
    pivot=(0.5, 0.5),
    rotate=0,
)
```

Places a child of `pz.anchor_layout` at `x`, `y` with `width` and `height` (in the layout's design size) and says how it follows a resize.

| Parameter | Description |
| --- | --- |
| `content` | The widget. |
| `x` | Left edge in the design size. |
| `y` | Top edge in the design size. |
| `width` | Width in the design size. |
| `height` | Height in the design size. |
| `anchor` | A preset of `pyzed.anchors.PRESETS` (`"top_right"`, `"bottom_wide"`, `"center"`, `"full"`...), words (`"left right bottom"`) or a tuple of edges. |
| `min_width` | Smallest width when it stretches (`0`: no limit). |
| `min_height` | Smallest height when it stretches. |
| `max_width` | Largest width when it stretches (`0`: no limit). |
| `max_height` | Largest height when it stretches. |
| `pivot` | `(x, y)` from `0` to `1`: the point that stays put when a limit stops it, and that `rotate` turns around. |
| `rotate` | Degrees clockwise. |

```python
pz.anchor(ui.button("Close", on_close), x=284, y=252, width=100, height=32, anchor="bottom_right")
```

### `anchor_layout`

```python
anchor_layout(children, *, design=None, width='fill', height='fill')
```

Places children made with `pz.anchor` freely, like a designed form: when it is resized, each child keeps its distance to the edges it is anchored to, stretches between opposite ones and stays centered otherwise. Later children are drawn on top. See [Anchored layouts](https://albakore.github.io/pyzed/guides/layout/#anchored-layouts).

| Parameter | Description |
| --- | --- |
| `children` | Children made with `pz.anchor(...)` (`None` is skipped). |
| `design` | `(width, height)` the children were laid out in; by default the smallest size that holds them. |
| `width` | Width. |
| `height` | Height. |

```python
pz.anchor_layout([
    pz.anchor(ui.heading("Report"), x=16, y=12, width=368, height=28, anchor="top_wide"),
    pz.anchor(ui.button("Close", on_close), x=284, y=252, width=100, height=32, anchor="bottom_right"),
], design=(400, 300))
```

### `place`

```python
place(
    rect,
    anchor,
    design,
    actual,
    *,
    min_size=(0, 0),
    max_size=(0, 0),
    pivot=(0.5, 0.5),
)
```

Where a box designed in a parent of size `design` goes in a parent of size `actual`, following its anchor, with size limits and a pivot. The math behind `pz.anchor_layout` and designed forms.

| Parameter | Description |
| --- | --- |
| `rect` | `(x, y, width, height)` in the design size. |
| `anchor` | A preset, words or edges. |
| `design` | The parent's design size. |
| `actual` | The parent's current size. |
| `min_size` | `(width, height)` lower limits (`0`: none). |
| `max_size` | `(width, height)` upper limits (`0`: none). |
| `pivot` | The point that stays put when a limit stops the box from stretching. |

```python
anchors.place((20, 20, 100, 30), "top_right", design=(400, 300), actual=(600, 300))  # (220, 20, 100, 30)
```

### `PRESETS`

The 16 anchor presets by name (`top_left`, `top_center`, `top_right`, `top_wide`, `center_left`, `center`, `center_right`, `center_wide`, `bottom_left`, `bottom_center`, `bottom_right`, `bottom_wide`, `left_tall`, `center_tall`, `right_tall`, `full`), each the tuple of edges it anchors to.

### `edges`

```python
edges(anchor)
```

The edges of an anchor given as a preset name, words or edges. Raises `ValueError` for anything else.

| Parameter | Description |
| --- | --- |
| `anchor` | What to read. |

### `preset_of`

```python
preset_of(edges)
```

The name of the preset a set of edges matches (every set is one of the 16).

| Parameter | Description |
| --- | --- |
| `edges` | Edges. |

### `preset`

```python
preset(horizontal, vertical)
```

The preset placed `horizontal` (`left`, `center`, `right`, `wide`) and `vertical` (`top`, `center`, `bottom`, `tall`).

| Parameter | Description |
| --- | --- |
| `horizontal` | Placement on the x axis. |
| `vertical` | Placement on the y axis. |

### `axes`

```python
axes(edges)
```

The `(horizontal, vertical)` placement of a set of edges, such as `("right", "top")`.

| Parameter | Description |
| --- | --- |
| `edges` | Edges. |

### `snap_to`

```python
snap_to(anchor, rect, parent, margin=0.0)
```

A box moved (and sized, on stretched axes) to sit where an anchor points: against the anchored edges, centered or filling the parent, `margin` pixels in.

| Parameter | Description |
| --- | --- |
| `anchor` | A preset, words or edges. |
| `rect` | The box. |
| `parent` | The parent's size. |
| `margin` | Distance to the edges. |

### `offsets`

```python
offsets(rect, parent)
```

The distances `(left, top, right, bottom)` from each side of the parent to a box.

| Parameter | Description |
| --- | --- |
| `rect` | The box. |
| `parent` | The parent's size. |

### `pivot_offset`

```python
pivot_offset(size, pivot, rotate=0.0, scale=1.0)
```

The translation that makes a rotation and a scale (which turn around a box's center) turn around `pivot` instead.

| Parameter | Description |
| --- | --- |
| `size` | The box's size. |
| `pivot` | `(x, y)` from `0` to `1`. |
| `rotate` | Degrees clockwise. |
| `scale` | Scale factor. |

### `focusable`

```python
focusable(
    content,
    on_key=None,
    *,
    keys=None,
    id=None,
    ring_color=None,
    ring_radius=4.0,
    ring_offset=2.0,
)
```

Lets any widget take the keyboard focus like a text field: a click or Tab focuses it (`Command.focus(id)` too) and, while it has it, the combos in `keys` call `on_key(combo)` instead of reaching the app's `on_key`. A ring is drawn around it once the keyboard is used on it. The library's switches, check boxes, sliders, segmented controls and radio groups use it.

| Parameter | Description |
| --- | --- |
| `content` | The control. |
| `on_key` | Called with the combo (`"space"`, `"shift-right"`…) of each key in `keys` pressed while it has the focus. `None` leaves `content` unfocusable. |
| `keys` | The combos it takes (by default Space, Enter, the arrows, Home and End); `"*"` takes every key. Tab is left to move the focus. |
| `id` | Stable identifier used to focus or scroll it with a `Command`. |
| `ring_color` | Color of the focus ring (none by default). |
| `ring_radius` | Corner radius of the ring. |
| `ring_offset` | Pixels between the control and the ring. |

```python
pz.focusable(stars, lambda combo: self.rate(+1 if combo == "right" else -1), keys=["left", "right"], ring_color="#528bff")
```

### `window_edges`

```python
window_edges(content, *, border=6.0, enabled=True)
```

Wraps the whole view of a window without system decorations so that pressing near its edges resizes the window (the corners take twice as much room). `ui.window_frame` already uses it.

| Parameter | Description |
| --- | --- |
| `content` | The window's whole view. |
| `border` | Width in pixels of the area that resizes. |
| `enabled` | `False` turns it off (for a maximized window). |

```python
pz.window_edges(view, enabled=not self.window_maximized)
```

### `resizable`

```python
resizable(
    content,
    *,
    edge='right',
    size=240.0,
    min_size=80.0,
    max_size=None,
    on_resize=None,
    color=None,
    hover_color=None,
    thickness=1.0,
    handle=8.0,
    width=None,
    height=None,
)
```

A panel whose `edge` can be dragged to resize it. It keeps the size the user drags it to; `on_resize(size)` is called when a drag ends so you can save it. Changing `size` later resets it.

| Parameter | Description |
| --- | --- |
| `content` | The panel's content. |
| `edge` | The edge with the handle: `"right"` (a left sidebar), `"left"`, `"top"` (a bottom panel) or `"bottom"`. |
| `size` | Starting width (height for top/bottom edges). |
| `min_size` | Smallest size. |
| `max_size` | Largest size. |
| `on_resize` | Called with the new size when a drag ends. |
| `color` | Line color. |
| `hover_color` | Line color while hovered or dragged. |
| `thickness` | Line thickness. |
| `handle` | Width of the area that can be grabbed. |
| `width` | Width for top/bottom edges. |
| `height` | Height for left/right edges. |

```python
pz.row([pz.resizable(sidebar, edge="right", size=240, on_resize=self.save_width), editor])
```

### `split`

```python
split(
    first,
    second,
    *,
    ratio=0.5,
    on_resize=None,
    vertical=False,
    min_size=80.0,
    min_size_second=None,
    color=None,
    hover_color=None,
    thickness=1.0,
    handle=8.0,
    width=None,
    height=None,
)
```

Two panes with a draggable divider. For the theme style use `ui.split`.

| Parameter | Description |
| --- | --- |
| `first` | First pane. |
| `second` | Second pane. |
| `ratio` | Proportion of the first pane (0–1). The split keeps the ratio the user drags to until this changes. |
| `on_resize` | Callable that receives the new ratio while dragging. |
| `vertical` | Stacks the panes top/bottom. |
| `min_size` | Minimum size of the first pane. |
| `min_size_second` | Minimum size of the second pane. |
| `color` | Divider color. |
| `hover_color` | Divider color on hover or while dragging. |
| `thickness` | Line thickness. |
| `handle` | Width of the draggable area. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |

### `pin`

```python
pin(content, *, x=0.0, y=0.0, width=None, height=None)
```

Places `content` at `(x, y)` inside a box. Use it in a `stack` to position popovers and context menus.

| Parameter | Description |
| --- | --- |
| `content` | Content: a `Widget`, a string or a number (converted to text). |
| `x` | Horizontal position. |
| `y` | Vertical position. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |

### `responsive`

```python
responsive(function)
```

Builds its content with `function(width, height)` using the space actually available, so the layout can adapt (for example, hiding a sidebar when the window is narrow).

| Parameter | Description |
| --- | --- |
| `function` | Function that receives `(width, height)` and returns a widget. |

### `FlexItem`

```python
class FlexItem
```

A child of `pz.flex` with its own sizing; made with `pz.flex_item`.

## Text and icons

### `text`

```python
text(
    content,
    *,
    size=None,
    color=None,
    font=None,
    weight=None,
    italic=False,
    line_height=None,
    align_x=None,
    align_y=None,
    width=None,
    height=None,
    wrap=True,
    selectable=None,
    selection_color=None,
)
```

A piece of text.

| Parameter | Description |
| --- | --- |
| `content` | Content: a `Widget`, a string or a number (converted to text). |
| `size` | Font size. |
| `color` | Text or icon color. |
| `font` | `"sans"` (IBM Plex Sans), `"mono"`, `"icons"`, `"serif"` or the name of a family loaded with `load_font`. |
| `weight` | `"thin"`, `"light"`, `"normal"`, `"medium"`, `"semibold"`, `"bold"`, `"black"` or a number (100–900). |
| `italic` | Italic. |
| `line_height` | Line height relative to the size (1.0, 1.5…). |
| `align_x` | Horizontal alignment: `"start"`/`"left"`, `"center"`, `"end"`/`"right"`. |
| `align_y` | Vertical alignment: `"start"`/`"top"`, `"center"`, `"end"`/`"bottom"`. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `wrap` | Line wrapping. With `False` the text doesn't wrap. |
| `selectable` | `True` lets the mouse select the text (drag, double-click a word, triple-click a block) and Ctrl+C copy it. A string names a selection group: the texts and Markdown of one group form a single selection, in the order they are drawn (the lines of a log, the messages of a chat). |
| `selection_color` | Color behind the selected text. |

### `icon`

```python
icon(name, *, size=16, color=None)
```

A [Lucide](https://lucide.dev) icon. `color` defaults to the surrounding text color.

| Parameter | Description |
| --- | --- |
| `name` | Icon name (`pyzed icons` lists them). |
| `size` | Size in pixels. |
| `color` | Color. |

```python
pz.icon("folder", size=16, color="#74ade8")
```

### `svg`

```python
svg(
    source,
    *,
    width=None,
    height=None,
    color=None,
    content_fit=None,
    opacity=1.0,
    rotation=0.0,
)
```

An SVG image.

| Parameter | Description |
| --- | --- |
| `source` | Path to an `.svg`, the SVG code as a string (starting with `<`) or `bytes`. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `color` | If given, tints the whole SVG with that color (useful for monochrome icons). |
| `content_fit` | `"contain"`, `"cover"`, `"fill"`, `"none"` or `"scale-down"`. |
| `opacity` | Opacity from 0 to 1. |
| `rotation` | Rotation in degrees. |

## Images and content

### `image`

```python
image(
    source,
    *,
    width=None,
    height=None,
    content_fit=None,
    filter='linear',
    opacity=1.0,
    radius=0.0,
    rotation=0.0,
    scale=1.0,
    size=None,
)
```

A bitmap image (PNG, JPEG, GIF, BMP, WebP…) from a path or `bytes`, or raw RGBA pixels.

| Parameter | Description |
| --- | --- |
| `source` | File path, `bytes` of the encoded file, or raw RGBA pixels with `size=(width, height)`. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `content_fit` | `"contain"`, `"cover"`, `"fill"`, `"none"` or `"scale-down"`. |
| `filter` | `"linear"` (smooth) or `"nearest"` (crisp pixels, for pixel art). |
| `opacity` | Opacity from 0 to 1. |
| `radius` | Corner radius. |
| `rotation` | Rotation in degrees. |
| `scale` | Scale. |
| `size` | `(width, height)` when `source` is raw RGBA pixels. |

```python
pz.image("photo.jpg", width=320, content_fit="cover", radius=8)
```

### `image_viewer`

```python
image_viewer(
    source,
    *,
    width=None,
    height=None,
    min_scale=0.25,
    max_scale=10.0,
    scale_step=0.1,
    filter='linear',
    size=None,
)
```

An image you can pan (by dragging) and zoom (mouse wheel), like Iced's viewer.

| Parameter | Description |
| --- | --- |
| `source` | File path, `bytes` of the encoded file, or raw RGBA pixels with `size=(width, height)`. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `min_scale` | Minimum zoom. |
| `max_scale` | Maximum zoom. |
| `scale_step` | How much the zoom changes per wheel step. |
| `filter` | `"linear"` (smooth) or `"nearest"` (crisp pixels, for pixel art). |
| `size` | `(width, height)` for raw RGBA pixels. |

### `markdown`

```python
markdown(
    source,
    *,
    size=14.0,
    color=None,
    link_color=None,
    code_color=None,
    code_bg=None,
    on_link=None,
    width=None,
    selectable=None,
    selection_color=None,
)
```

Renders Markdown (headings, lists, code blocks, quotes, tables, links…). For the theme colors use `ui.markdown`.

| Parameter | Description |
| --- | --- |
| `source` | The Markdown text. |
| `size` | Size. |
| `color` | Text or icon color. |
| `link_color` | Link color. |
| `code_color` | Code color. |
| `code_bg` | Code background. |
| `on_link` | Callable that receives the URL when a link is clicked. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `selectable` | `True` lets the mouse select the text (drag, double-click a word, triple-click a block) and Ctrl+C copy it. A string names a selection group: the texts and Markdown of one group form a single selection, in the order they are drawn (the lines of a log, the messages of a chat). |
| `selection_color` | Color behind the selected text. |

### `rich_text`

```python
rich_text(
    spans,
    *,
    size=None,
    color=None,
    font=None,
    line_height=None,
    width=None,
    align_x=None,
    wrap=True,
)
```

Text made of spans with different styles. Plain strings are unstyled spans.

| Parameter | Description |
| --- | --- |
| `spans` | List of `span(...)` or strings. |
| `size` | Size. |
| `color` | Text or icon color. |
| `font` | Font of the span or text (family name, e.g. `"IBM Plex Mono"`). |
| `line_height` | Line height. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `align_x` | Horizontal alignment: `"start"`/`"left"`, `"center"`, `"end"`/`"right"`. |
| `wrap` | Line wrapping / moves children to a new row when they don't fit. |

```python
pz.rich_text(["Click ", pz.span("here", color="#74ade8", underline=True, link=self.open), " to open."])
```

### `span`

```python
span(
    text,
    *,
    color=None,
    size=None,
    font=None,
    weight=None,
    italic=False,
    bg=None,
    radius=0.0,
    padding=None,
    underline=False,
    strikethrough=False,
    link=None,
)
```

A styled span for `rich_text`. With `link`, clicking it sends (or calls) that value.

| Parameter | Description |
| --- | --- |
| `text` | The text. |
| `color` | Text or icon color. |
| `size` | Size. |
| `font` | Font of the span or text (family name, e.g. `"IBM Plex Mono"`). |
| `weight` | Font weight: `"normal"`, `"medium"`, `"semibold"` or `"bold"`. |
| `italic` | If `True`, the span is drawn in italics. |
| `bg` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `radius` | Background radius. |
| `padding` | Inner padding: `8`, `(vertical, horizontal)` or `(top, right, bottom, left)`. |
| `underline` | Underline. |
| `strikethrough` | Strikethrough. |
| `link` | Message or callable on click. |

### `Span`

The type of the spans created by `pz.span`.

### `qr_code`

```python
qr_code(data, *, cell_size=4.0, color=None, bg=None)
```

A QR code that encodes `data`.

| Parameter | Description |
| --- | --- |
| `data` | The text or URL to encode. |
| `cell_size` | Size of each module in pixels. |
| `color` | Text or icon color. |
| `bg` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |

### `shader`

```python
shader(
    code,
    *,
    uniforms=None,
    textures=None,
    width=None,
    height=None,
    animate=True,
    time=None,
    fallback=None,
)
```

A widget painted on the GPU by your WGSL `fn shade(uv, px, size, time) -> vec4<f32>`, which returns each pixel's color, or by a shader graph made of nodes (a `.pzshad` path or a [`pyzed.shading`](https://albakore.github.io/pyzed/reference/shading/) `Graph` or `Shader`). Each entry of `uniforms` becomes a function of the same name (`{"speed": 2}` -> `speed()`); `mouse()` gives the pointer. Without a GPU the widget shows `fallback`. Raises `ValueError` with the compiler's message for invalid code. See the [shaders](https://albakore.github.io/pyzed/shading/shaders/) guide.

| Parameter | Description |
| --- | --- |
| `code` | WGSL source that defines `shade` (and any helper functions), or a `.pzshad` path, `Graph` or `Shader`. |
| `uniforms` | Up to 32 named values: a number, 2 to 4 numbers or a color. With a `.pzshad`, the shader's mutable variables by name. |
| `textures` | Up to 8 images, `{name: path}`: each becomes `name(uv)`, the image's color at `uv`. |
| `width` | Width (`"fill"` by default). |
| `height` | Height (`"fill"` by default). |
| `animate` | Redraw every frame so `time` moves (`True`). |
| `time` | A fixed `time` in seconds, for a still frame. |
| `fallback` | Color or gradient shown without a GPU. |

### `canvas`

```python
canvas(
    shapes=None,
    *,
    width=None,
    height=None,
    id=None,
    on_press=None,
    on_release=None,
    on_right_press=None,
    on_move=None,
    on_scroll=None,
    cursor=None,
)
```

A 2D drawing surface. `shapes` is a list created with [`pyzed.draw`](https://albakore.github.io/pyzed/reference/draw/). Mouse callbacks receive coordinates relative to the canvas. With an `id`, the geometry is cached between frames and only recomputed when the shapes change. See the [drawing with canvas](https://albakore.github.io/pyzed/guides/canvas/) guide.

| Parameter | Description |
| --- | --- |
| `shapes` | List of `pyzed.draw` shapes (nested lists are accepted). |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `id` | Enables the geometry cache. |
| `on_press` | Callable that receives `(x, y)` on press. |
| `on_release` | Callable that receives `(x, y)` on release. |
| `on_right_press` | Callable that receives `(x, y)` on right click. |
| `on_move` | Called with `(x, y)` when the mouse moves. |
| `on_scroll` | Callable that receives `(dx, dy)` in lines when the wheel is used. |
| `cursor` | Mouse cursor (`"crosshair"`, `"pointer"`…). |

## Interaction

### `button`

```python
button(
    content,
    on_press=None,
    *,
    padding=None,
    width=None,
    height=None,
    bg=None,
    color=None,
    border_color=None,
    border_width=0.0,
    radius=None,
    shadow=None,
    hover_bg=None,
    hover_color=None,
    hover_border_color=None,
    pressed_bg=None,
    disabled_color=None,
    clip=False,
)
```

A button with no predefined style. For the themed button use `ui.button`.

| Parameter | Description |
| --- | --- |
| `content` | Button content. |
| `on_press` | Message or callable sent on press. `None` disables the control. |
| `padding` | Inner padding: `8`, `(vertical, horizontal)` or `(top, right, bottom, left)`. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `bg` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `color` | Text or icon color. |
| `border_color` | Border color. |
| `border_width` | Border width in pixels. |
| `radius` | Corner radius: a number or `(top_left, top_right, bottom_right, bottom_left)`. |
| `shadow` | Shadow: `(color, (dx, dy), blur)`. |
| `hover_bg` | Background on hover. |
| `hover_color` | Text color on hover. |
| `hover_border_color` | Border color on hover. |
| `pressed_bg` | Background while pressed. |
| `disabled_color` | Text color when disabled. |
| `clip` | Clips content that overflows the bounds. |

### `text_input`

```python
text_input(
    value,
    *,
    placeholder='',
    on_input=None,
    on_submit=None,
    id=None,
    size=None,
    font=None,
    padding=None,
    width=None,
    secure=False,
    icon=None,
    icon_size=None,
    bg=None,
    border_color=None,
    hover_border_color=None,
    focus_border_color=None,
    border_width=None,
    radius=None,
    color=None,
    placeholder_color=None,
    selection_color=None,
    icon_color=None,
    align_x=None,
)
```

A controlled text field: it shows `value` and notifies you of changes through `on_input`. For the themed field use `ui.input`.

| Parameter | Description |
| --- | --- |
| `value` | Current text. |
| `placeholder` | Hint text shown when empty. |
| `on_input` | Callable that receives the new text on every keystroke. |
| `on_submit` | Message or callable sent when Enter is pressed. |
| `id` | Stable identifier used to focus or scroll it with a `Command`. |
| `size` | Font size. |
| `font` | Font family. |
| `padding` | Inner padding: `8`, `(vertical, horizontal)` or `(top, right, bottom, left)`. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `secure` | Hides the text (passwords). |
| `icon` | Icon character (use `pyzed.icons.glyph(name)`). |
| `icon_size` | Icon size. |
| `bg` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `border_color` | Border color. |
| `hover_border_color` | Border color on hover. |
| `focus_border_color` | Border color when focused. |
| `border_width` | Border width in pixels. |
| `radius` | Corner radius: a number or `(top_left, top_right, bottom_right, bottom_left)`. |
| `color` | Text or icon color. |
| `placeholder_color` | Placeholder color. |
| `selection_color` | Selection color. |
| `icon_color` | Icon color. |
| `align_x` | Horizontal alignment: `"start"`/`"left"`, `"center"`, `"end"`/`"right"`. |

### `mouse_area`

```python
mouse_area(
    content,
    *,
    on_press=None,
    on_release=None,
    on_right_press=None,
    on_double_click=None,
    on_enter=None,
    on_exit=None,
    on_move=None,
    on_scroll=None,
    on_middle_press=None,
    on_middle_release=None,
    cursor=None,
)
```

Detects mouse events over its content.

| Parameter | Description |
| --- | --- |
| `content` | Content: a `Widget`, a string or a number (converted to text). |
| `on_press` | Left click (on press). |
| `on_release` | On releasing the left button. |
| `on_right_press` | Right click (context menus). |
| `on_double_click` | Double click. |
| `on_enter` | The mouse enters. |
| `on_exit` | The mouse leaves. |
| `on_move` | Called with `(x, y)` when the mouse moves. |
| `on_scroll` | Callable that receives `(dx, dy)` in lines when the wheel is used. |
| `on_middle_press` | Middle-button click. |
| `on_middle_release` | Middle button released (pan gestures, for example). |
| `cursor` | `"pointer"`, `"text"`, `"grab"`, `"grabbing"`, `"crosshair"`, `"not-allowed"`, `"resize-horizontal"`, `"resize-vertical"`, `"move"` or `"default"`. |

### `hover`

```python
hover(base, top)
```

Shows `top` over `base` only while the mouse is over it (for example, a tab's close button).

| Parameter | Description |
| --- | --- |
| `base` | Widget underneath. |
| `top` | Widget that appears on hover. |

### `opaque`

```python
opaque(content)
```

Makes a widget block the mouse for whatever is below it in a `stack`.

| Parameter | Description |
| --- | --- |
| `content` | Content: a `Widget`, a string or a number (converted to text). |

### `tooltip`

```python
tooltip(
    content,
    tip,
    *,
    position='bottom',
    gap=4.0,
    bg=None,
    color=None,
    border_color=None,
    border_width=0.0,
    radius=None,
    shadow=None,
)
```

Shows `tip` next to `content` on hover. `ui.tooltip` adds the theme's style.

| Parameter | Description |
| --- | --- |
| `content` | Content: a `Widget`, a string or a number (converted to text). |
| `tip` | Tooltip content. |
| `position` | `"top"`, `"bottom"`, `"left"`, `"right"` or `"cursor"`. |
| `gap` | Distance from the content. |
| `bg` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `color` | Text or icon color. |
| `border_color` | Border color. |
| `border_width` | Border width in pixels. |
| `radius` | Corner radius: a number or `(top_left, top_right, bottom_right, bottom_left)`. |
| `shadow` | Shadow: `(color, (dx, dy), blur)`. |

### `popup`

```python
popup(base, content=None, *, on_dismiss=None, side='bottom', align='start', gap=4.0)
```

Shows `content` over everything else next to `base`, like the menu of a drop-down: it is not cut off by the panels `base` sits in, flips to the other side when it does not fit and stays inside the window. A press outside it (and outside `base`) or Escape calls `on_dismiss`. With `content=None` only `base` is shown. The date pickers open their calendars with it.

| Parameter | Description |
| --- | --- |
| `base` | The widget it belongs to (a field, a button). |
| `content` | What opens (a panel, a menu), or `None` while closed. |
| `on_dismiss` | Message or callable sent on a press outside or Escape. |
| `side` | `"bottom"`, `"top"`, `"right"` or `"left"` of `base`. |
| `align` | `"start"`, `"center"` or `"end"`: how it lines up with `base`. |
| `gap` | Space between `base` and the content. |

```python
pz.popup(field, panel if self.open else None, on_dismiss=self.close)
```

## Controls

### `checkbox`

```python
checkbox(
    checked,
    label=None,
    *,
    on_toggle=None,
    size=None,
    text_size=None,
    accent=None,
    bg=None,
    border_color=None,
    check_color=None,
    color=None,
)
```

A checkbox.

| Parameter | Description |
| --- | --- |
| `checked` | Current state. |
| `label` | Label text. |
| `on_toggle` | Callable that receives the new `bool` (or a message to send). |
| `size` | Box size. |
| `text_size` | Text size. |
| `accent` | Accent color (active part). |
| `bg` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `border_color` | Border color. |
| `check_color` | Check mark color. |
| `color` | Text or icon color. |

### `toggler`

```python
toggler(
    checked,
    label=None,
    *,
    on_toggle=None,
    size=None,
    text_size=None,
    accent=None,
    bg=None,
    border_color=None,
    knob_color=None,
    color=None,
)
```

An on/off switch.

| Parameter | Description |
| --- | --- |
| `checked` | Current state. |
| `label` | Label text. |
| `on_toggle` | Callable that receives the new `bool` (or a message to send). |
| `size` | Switch height. |
| `text_size` | Text size. |
| `accent` | Accent color (active part). |
| `bg` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `border_color` | Border color. |
| `knob_color` | Knob color. |
| `color` | Text or icon color. |

### `slider`

```python
slider(
    min,
    max,
    value,
    *,
    step=1.0,
    on_change=None,
    on_release=None,
    width=None,
    height=None,
    vertical=False,
    accent=None,
    bg=None,
    knob_color=None,
    border_color=None,
)
```

A slider between `min` and `max`.

| Parameter | Description |
| --- | --- |
| `min` | Minimum. |
| `max` | Maximum. |
| `value` | Current value. |
| `step` | Step. |
| `on_change` | Callable that receives the new value. |
| `on_release` | Sent when the knob is released. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `vertical` | Vertical orientation. |
| `accent` | Accent color (active part). |
| `bg` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `knob_color` | Knob color. |
| `border_color` | Border color. |

### `progress_bar`

```python
progress_bar(
    value,
    *,
    min=0.0,
    max=1.0,
    width=None,
    height=None,
    accent=None,
    bg=None,
    radius=2.0,
)
```

A progress bar.

| Parameter | Description |
| --- | --- |
| `value` | Current value. |
| `min` | Minimum. |
| `max` | Maximum. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `accent` | Accent color (active part). |
| `bg` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `radius` | Corner radius. |

### `vertical_slider`

```python
vertical_slider(min, max, value, **kwargs)
```

A vertical slider (`slider(..., vertical=True)`).

| Parameter | Description |
| --- | --- |
| `min` | Minimum. |
| `max` | Maximum. |
| `value` | Current value. |
| `kwargs` | Same as `slider`. |

### `pick_list`

```python
pick_list(
    options,
    selected=None,
    on_select=None,
    *,
    on_open=None,
    on_close=None,
    placeholder=None,
    width=None,
    padding=None,
    text_size=None,
    font=None,
    handle=None,
    handle_size=12.0,
    menu_height=None,
    bg=None,
    color=None,
    placeholder_color=None,
    handle_color=None,
    border_color=None,
    hover_border_color=None,
    radius=None,
    menu_bg=None,
    menu_color=None,
    menu_border_color=None,
    selected_bg=None,
    selected_color=None,
    focus_border_color=None,
    id=None,
)
```

A dropdown to choose one of `options`. `on_select(option)` receives the chosen one. For the themed dropdown use `ui.select`. It takes the keyboard focus like a text field (a click, Tab or `Command.focus(id)`) and keeps it after a choice: ↑/↓ then pick the previous or next option without opening it, Home/End the first and last and typing jumps to an option; Enter, Space, Alt+↓ or F4 open the menu, where ↑/↓ move, Enter picks and Esc closes.

| Parameter | Description |
| --- | --- |
| `options` | List of options. |
| `selected` | Current option. |
| `on_select` | Callable that receives the chosen item. |
| `on_open` | Sent when the menu opens. |
| `on_close` | Sent when the menu closes. |
| `placeholder` | Hint text shown when empty. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `padding` | Inner padding: `8`, `(vertical, horizontal)` or `(top, right, bottom, left)`. |
| `text_size` | Text size. |
| `font` | Font family. |
| `handle` | Arrow icon character. |
| `handle_size` | Arrow size. |
| `menu_height` | Maximum menu height. |
| `bg` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `color` | Text or icon color. |
| `placeholder_color` | Placeholder color. |
| `handle_color` | Arrow color. |
| `border_color` | Border color. |
| `hover_border_color` | Border color on hover. |
| `radius` | Corner radius: a number or `(top_left, top_right, bottom_right, bottom_left)`. |
| `menu_bg` | Menu background. |
| `menu_color` | Menu text. |
| `menu_border_color` | Menu border. |
| `selected_bg` | Background of the highlighted option. |
| `selected_color` | Text of the highlighted option. |
| `focus_border_color` | Border color while it has the keyboard focus. |
| `id` | Stable identifier used to focus or scroll it with a `Command`. |

### `radio`

```python
radio(
    label,
    selected,
    on_select=None,
    *,
    size=None,
    text_size=None,
    spacing=None,
    accent=None,
    bg=None,
    border_color=None,
    color=None,
)
```

A radio button. Group several yourself (or use `ui.radio_group`); `on_select` is sent when it is clicked.

| Parameter | Description |
| --- | --- |
| `label` | Label text. |
| `selected` | Whether it is checked. |
| `on_select` | Message or callable on click. |
| `size` | Size. |
| `text_size` | Text size. |
| `spacing` | Space between the circle and the text. |
| `accent` | Accent color (active part). |
| `bg` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `border_color` | Border color. |
| `color` | Text or icon color. |

## Code editor

### `code_editor`

```python
code_editor(
    id,
    text='',
    *,
    language='txt',
    size=14.0,
    line_height=None,
    font=None,
    width=None,
    height=None,
    padding=None,
    syntax=None,
    bg=None,
    color=None,
    selection_color=None,
    placeholder=None,
    placeholder_color=None,
    gutter=True,
    gutter_color=None,
    gutter_active_color=None,
    gutter_width=None,
    markers=None,
    wrap=False,
    on_change=None,
    on_cursor=None,
    active_line=None,
    scrollbar_color=None,
    annotations=None,
    whitespace=None,
    tab_size=None,
    capture_keys=None,
    on_scroll=None,
    auto_close=False,
    folding=False,
    minimap=None,
    minimap_thumb=None,
    cursor_shape='bar',
    cursor_width=2.0,
    cursor_blink=True,
    cursor_color=None,
    on_zoom=None,
    on_action=None,
    highlights=None,
    highlight_color=None,
    match_brackets=True,
    selection_highlight=True,
    keymap=None,
    scrollbar=True,
    readonly=False,
    hard_tabs=False,
    backspace_unindent=True,
    repeat_delay=None,
    repeat_rate=None,
    on_hover=None,
    hover_delay=500.0,
    sticky_scroll=0,
)
```

A code editor with syntax highlighting, line numbers and git markers, based on Iced's
`text_editor`. It is **uncontrolled**: `text` is only the initial value for that `id`; the
text, cursor and history live in Rust. Use `Command.set_editor_text` to replace it.
For the themed editor use [`ui.editor`](https://albakore.github.io/pyzed/components/code/).

| Parameter | Description |
| --- | --- |
| `id` | Identifies the buffer. Reuse it to keep state across renders. |
| `text` | Initial text. |
| `language` | Language extension or name (`"py"`, `"rs"`, `"json"`…). |
| `size` | Font size. |
| `line_height` | Line height in pixels. |
| `font` | Family (monospace by default). |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `padding` | Inner padding: `8`, `(vertical, horizontal)` or `(top, right, bottom, left)`. |
| `syntax` | Map of TextMate scopes to colors (provided by `Theme.syntax_scopes()`). |
| `bg` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `color` | Text or icon color. |
| `selection_color` | Selection color. |
| `placeholder` | Hint text shown when empty. |
| `placeholder_color` | Placeholder color. |
| `gutter` | Shows line numbers. |
| `gutter_color` | Line number color. |
| `gutter_active_color` | Color of the cursor line's number. |
| `gutter_width` | Gutter width (automatic by default). |
| `markers` | `{line: color}` for git markers in the gutter (lines from 1). |
| `wrap` | Line wrapping. |
| `on_change` | Callable that receives the full text after each edit. |
| `on_cursor` | Callable that receives `(line, column)`, from 1. |
| `active_line` | Background color of the cursor line. |
| `scrollbar_color` | Scrollbar color. |
| `annotations` | `{line: "text"}` or `{line: ("text", color)}`: virtual text at the end of the line (code lens, diagnostics). |
| `whitespace` | Draws spaces as `·` and tabs as `→` in this color. |
| `tab_size` | Tab inserts spaces up to the next multiple; Enter keeps the indentation; Backspace removes a level. |
| `capture_keys` | Keys the editor leaves to the app's `on_key` (`"up"`, `"enter"`…), e.g. while a completion list is open. |
| `on_scroll` | Called on scroll. |
| `auto_close` | Typing a bracket or quote also inserts its closing pair. |
| `folding` | Fold chevrons in the gutter and Ctrl+Shift+[ / ]. |
| `minimap` | Width of the minimap in pixels (`None`: no minimap). |
| `minimap_thumb` | Color of the minimap's visible-area highlight. |
| `cursor_shape` | `"bar"`, `"block"`, `"underline"` or `"hollow"`. |
| `cursor_width` | Width of the bar cursor. |
| `cursor_blink` | Whether the cursor blinks. |
| `cursor_color` | Cursor color. |
| `on_zoom` | Callable that receives `1`, `-1` or `0` for Ctrl+= / Ctrl+- / Ctrl+0 and Ctrl+wheel. |
| `on_action` | Callable that receives the name of each editor action that runs (`"undo"`, `"select_next"`…). |
| `highlights` | Ranges painted behind the text (search results): `[(line, column, end_line, end_column)]`, from 1, with exclusive ends. |
| `highlight_color` | Color of `highlights`. |
| `match_brackets` | Outlines the bracket that matches the one next to the cursor. |
| `selection_highlight` | Highlights the other occurrences of the selected text. |
| `keymap` | Zed-style `{binding: action}` dict; `None` as the action removes a default key (`pyzed.ui.editor.keymap_for` builds one from per-action overrides). |
| `scrollbar` | `False` hides the scrollbars. |
| `readonly` | `True` lets the text be selected and copied but not changed (a log, a traceback). |
| `hard_tabs` | With `tab_size`: Tab, Enter and indent (Ctrl+]) use tab characters instead of spaces. |
| `backspace_unindent` | With `tab_size`: Backspace in leading spaces removes a whole level (`False`: one space). |
| `repeat_delay` | Milliseconds Backspace and Delete wait, held down, before repeating (`None`: the system's). |
| `repeat_rate` | Deletions per second at most while Backspace or Delete is held down (`None`: the system's pace). |
| `on_hover` | Callable that receives `{line, column, start, end, x, y, height}` (the word under the mouse, from 1, and its place in the editor) after the mouse rests on it, and `None` when it leaves (hover cards). |
| `hover_delay` | Milliseconds the mouse rests on a word before `on_hover` is called. |
| `sticky_scroll` | How many lines of the enclosing blocks (`class`, `def`, `if`…) stay pinned at the top while scrolling (`0`: none). |

## Styles

### `Style`

```python
class Style
```

A reusable set of style properties for `widget.style(...)`, a component's `style=` or `App.style`. Combine styles with `|` (the right one wins). See [Styles](https://albakore.github.io/pyzed/theming/styles/).

| Parameter | Description |
| --- | --- |
| `styles` | Styles, dicts or style names to start from. |
| `props` | Properties: `background`, `color`, `font`, `weight`, `italic`, `size`, `line_height`, `border_color`, `border_width`, `border` (`(width, color)`), `radius`, `shadow`, `padding`, `margin`, `width`, `height`, `max_width`, `max_height`, `min_width`, `min_height`, `align_x`, `align_y`, `clip`. Effects: `opacity`, `translate` (`(x, y)`, pixels or `"50%"`), `scale`, `glow` (a color, a size or `(color, size)`), `bloom` (a color or `(color, intensity)`) and `glass` (`True`, a tint or `{"tint", "strength"}`). States: `hover`, `pressed` (or `active`) and `focus`, each with the properties to show then. `transition`: milliseconds, `True` or `{"duration", "easing", "delay"}`. `media`: `{query: style}` applied when the window matches. Colors may be theme tokens. |

```python
card = pz.Style(background="panel", border=(1, "border"), radius=8, padding=12)
pz.column([...]).style(card | pz.Style(shadow=("#0006", (0, 4), 12)))
```

**Methods and properties**

#### `Style.get`

```python
Style.get(key, default=None)
```

Returns a property's value (aliases accepted), or `default` when it is not set.

#### `Style.merge`

```python
Style.merge(*styles, **props)
```

A new style with `styles` and `props` on top of this one.

#### `Style.without`

```python
Style.without(*keys)
```

A new style without these properties.

#### `Style.text`

```python
Style.text()
```

Only the text properties (what a style passes down to the texts inside).

#### `Style.to_dict`

```python
Style.to_dict()
```

JSON-friendly properties (gradients and paints become dicts).

#### `Style.from_dict`

```python
@classmethod
Style.from_dict(data)
```

Builds a style from data made by `to_dict` (aliases accepted).

### `define_style`

```python
define_style(name, *styles, **props)
```

Names a style so widgets can use it by name: `widget.style("card")`. Returns it.

| Parameter | Description |
| --- | --- |
| `name` | The style's name. |
| `styles` | Styles to merge. |
| `props` | Properties on top. |

### `stylesheet`

```python
stylesheet(rules=None, **classes)
```

Adds CSS-like rules, `{selector: style}`, that widgets get with `widget.classes(...)` and components with `class_=`/`id=`. Selectors: `.class`, `.a.b`, `#id`, a component's class name (`"Rating"`), an optional `:hover`, `:pressed`/`:active` or `:focus`, and comma lists. More specific selectors win (ids, then classes, then names), then later rules. A selector given again replaces its rule. Returns every rule. See [Stylesheets](https://albakore.github.io/pyzed/theming/styles/#stylesheets).

| Parameter | Description |
| --- | --- |
| `rules` | A `{selector: style}` dict. |
| `classes` | Classes by keyword: `card={...}` is `".card"`. |

```python
pz.stylesheet({
    ".card": {"background": "panel", "padding": 16, "radius": 8},
    ".card:hover": {"border_color": "accent"},
})
pz.column([...]).classes("card")
```

### `clear_stylesheet`

```python
clear_stylesheet()
```

Removes every rule added with `pz.stylesheet`.

### `media`

```python
media(query=None, **conditions)
```

Whether the window being drawn matches a media query, like CSS `@media`. See [Responsive styles](https://albakore.github.io/pyzed/theming/styles/#responsive-styles).

| Parameter | Description |
| --- | --- |
| `query` | `"max_width: 600"`, `"(min_width: 768px) and (orientation: landscape)"` or a breakpoint (`"md"`). |
| `conditions` | The same by keyword: `min_width`, `max_width`, `min_height`, `max_height`, `orientation`, `theme`. |

```python
sidebar = None if pz.media("max_width: 600") else self.sidebar()
```

### `viewport`

```python
viewport()
```

The size of the window being drawn, `(width, height)` in logical pixels, like `window.innerWidth` and `innerHeight`.

### `current_breakpoint`

```python
current_breakpoint()
```

The widest breakpoint the window reaches: `"xs"` (under 640 px), `"sm"`, `"md"`, `"lg"`, `"xl"` or `"xxl"`.

### `set_style`

```python
set_style(*styles, **props)
```

Sets the global style for every window, under each window's `style`. Without arguments it clears it.

| Parameter | Description |
| --- | --- |
| `styles` | Styles to merge. |
| `props` | Properties on top. |

### `Gradient`

```python
class Gradient
```

A linear gradient for backgrounds. Angles follow CSS: 0 up, 90 right, 180 (the default) down. Up to 8 stops.

| Parameter | Description |
| --- | --- |
| `stops` | Colors, spread evenly, or `(offset, color)` pairs with offsets from 0 to 1. |
| `angle` | Direction in degrees. |

```python
pz.container(None, height=80).style(background=pz.Gradient(["#f97316", "#7c3aed"], angle=90))
```

**Methods and properties**

#### `Gradient.to_value`

```python
Gradient.to_value()
```

`(angle, [(offset, "#rrggbbaa"), ...])`, the form widgets take as `gradient=`.

#### `Gradient.to_dict`

```python
Gradient.to_dict()
```

Returns the gradient as JSON-ready data: `{"type": "linear", "angle", "stops"}`.

### `Mask`

```python
class Mask
```

An opacity mask for a `Paint`: how visible the fill is along a direction. On a gradient it follows the gradient's direction.

| Parameter | Description |
| --- | --- |
| `stops` | Opacities (0 to 1), spread evenly, or `(offset, opacity)` pairs. |
| `angle` | Direction when the fill is a plain color. |

**Methods and properties**

#### `Mask.at`

```python
Mask.at(offset)
```

Returns the opacity (0 to 1) at `offset` (0 to 1), interpolating between stops.

#### `Mask.to_dict`

```python
Mask.to_dict()
```

Returns the mask as JSON-ready data: `{"angle", "stops"}`.

### `Paint`

```python
class Paint
```

A fill: a color or `Gradient` with an overall opacity and an optional `Mask`. Works anywhere a background does.

| Parameter | Description |
| --- | --- |
| `fill` | A color or a `Gradient`. |
| `opacity` | 0 to 1, multiplies the fill's own alpha. |
| `mask` | A `pz.Mask`. |

```python
pz.Paint("#3b82f6", opacity=0.8, mask=pz.Mask([1, 0]))  # fades out downwards
```

**Methods and properties**

#### `Paint.resolve`

```python
Paint.resolve()
```

`(color, gradient)`: what a container draws (one of them is `None`).

#### `Paint.to_dict`

```python
Paint.to_dict()
```

Returns the paint as JSON-ready data: `fill`, `opacity` and `mask` when there is one.

### `global_style`

```python
global_style()
```

The style set with `set_style` (`None` if none).

### `named_styles`

```python
named_styles()
```

The styles defined with `define_style`, by name.

### `apply_global`

```python
apply_global(view, style=None)
```

`view` with a window's global style: text properties fill in what texts leave unset.

### `themed`

```python
themed(theme, style)
```

`theme` with a global style's text color, background, border color, size and radius.

### `to_hex`

```python
to_hex(color)
```

Any color as `"#rrggbb"` or `"#rrggbbaa"` (theme tokens resolved).

### `paint_from_dict`

```python
paint_from_dict(data)
```

Rebuilds a `Gradient` or `Paint` saved with `to_dict()`.

## Animation

### `Animation`

```python
@dataclass
class Animation(keyframes=(), duration=300, delay=0, easing='ease', repeat=1, direction='normal', fill='both', on='mount', category='custom', description='', _frames=())
```

A keyframe animation, like a CSS `@keyframes` rule with its timing.

`keyframes` is a list of `{property: value}` frames (spread evenly; a frame may set
`offset` and `easing`) or a dict from offsets (`0` to `1`, `"50%"`, `"from"`,
`"to"`) to frames. A property missing at the start or end goes from or to the widget's
own value, and `None` names that value explicitly:

```python
pz.Animation([{"opacity": 0, "y": 12}, {"opacity": 1, "y": 0}], duration=250)
pz.Animation({0: {"scale": 1}, "50%": {"scale": 1.1}, 1: {"scale": 1}}, repeat="infinite")
```

The other fields are the defaults `animate()` options override. `category` and
`description` tell editors where and how to show a preset.

**Methods and properties**

#### `Animation.properties`

```python
Animation.properties  # property
```

The properties the keyframes change, in order of appearance.

#### `Animation.total`

```python
Animation.total  # property
```

Milliseconds from the start to the end (`inf` when it repeats forever).

#### `Animation.with_options`

```python
Animation.with_options(**options)
```

A copy with other timing or trigger (`duration`, `easing`, `on`...).

#### `Animation.compile`

```python
Animation.compile(**options)
```

The plain data the native side plays (`animate()` calls it).

#### `Animation.to_dict`

```python
Animation.to_dict()
```

JSON-ready data (`Animation.from_dict` reads it back).

#### `Animation.from_dict`

```python
@classmethod
Animation.from_dict(data)
```

Rebuilds an animation saved with `to_dict`.

### `Trigger`

```python
class Trigger
```

Starts an animation from your code, like a button you press in a handler.

Keep one on the app, give it to `animate(on=...)` in `view()` and call `fire()`
whenever the animation should play (from the start, even if it is still running):

```python
class Login(pz.App):
    def __init__(self):
        self.wrong = pz.Trigger()

    def view(self):
        return ui.input(self.password, self.set_password).animate("shake", on=self.wrong)

    def submit(self):
        if not self.check():
            self.wrong.fire()          # the field shakes now
```

Nothing plays when the widget appears: only `fire()` starts it. `count` says how
many times it was fired. `fire` takes and ignores any arguments, so it can be a
callback itself: `ui.button("Shake", self.wrong.fire)`.

**Methods and properties**

#### `Trigger.fire`

```python
Trigger.fire(*_args)
```

Plays the animations that use this trigger, from the start.

### `define_animation`

```python
define_animation(name, animation=None, **options)
```

Names an animation so `animate(name)` plays it; returns it.

`define_animation("wiggle", [{"x": 0}, {"x": -4}, {"x": 4}, {"x": 0}], duration=300)`

### `presence`

```python
presence(
    content,
    key,
    *,
    enter='fade_in',
    exit='fade_out',
    id=None,
    duration=None,
    easing=None,
)
```

Shows `content` and, when `key` changes, animates the old content out (`exit`)
while the new one comes in (`enter`), like page transitions:

```python
pz.presence(self.page_view(), key=self.page, enter="slide_in_right", exit="fade_out")
```

`id` tells presences apart (it defaults to where it is called from, so give one when
the same line makes several). `duration` and `easing` override both animations'.

### `stagger`

```python
stagger(items, animation='fade_in_up', *, step=40, delay=0, **options)
```

`items` with the same animation, each starting `step` milliseconds after the previous
one (a list that cascades in):

```python
pz.column(pz.stagger([row(i) for i in items], "fade_in_up", step=30))
```

### `set_reduced_motion`

```python
set_reduced_motion(on=True)
```

Turns motion off (`True`) or back on: animations show their resting state at once.

By default Pyzed follows the system's "reduce motion" accessibility setting (read when
the app starts, see `pyzed.system_reduced_motion`). `True` or `False` overrides it
(for example from your app's own settings, or in tests) and `None` follows the system
again. The `PYZED_REDUCED_MOTION` environment variable (`1` or `0`) overrides it too.

### `reduced_motion`

```python
reduced_motion()
```

Whether reduced motion is on.

### `system_reduced_motion`

```python
system_reduced_motion()
```

Whether the system asks apps to reduce motion (`None` if unknown).

### `animation`

```python
animation(name)
```

The animation named `name` (a preset or one defined with `define_animation`).

### `presets`

```python
presets(category=None)
```

The named animations (all, or one `category`: entrance, exit, attention, interaction, loop).

### `ease`

```python
ease(easing, t)
```

`easing` at `t` (0 to 1), the curve animations use: `ease("ease_out", 0.5)`.

Handy to animate your own drawings (`pz.canvas`) with the same curves.

### `window_animations`

```python
window_animations(window, closing=False)
```

The animation a window plays when it opens (or closes), from its `transition` and
`exit_transition` (an empty list when it has none).

### `PRESETS`

Every named animation (the built-in presets and the ones added with `define_animation`), mapped to its `Animation`. See [the preset list](https://albakore.github.io/pyzed/animation/presets/).

### `CATEGORIES`

Preset categories: `entrance`, `exit`, `attention`, `interaction` and `loop`.

### `EASINGS`

Easing names (`linear`, `ease`, `ease_out_cubic`, `ease_out_back`, `spring`...). `animate()` also takes `(x1, y1, x2, y2)` cubic Béziers and `"steps(n)"`.

### `TRIGGERS`

What plays an animation: `mount`, `hover`, `press`, `focus`, `click`, `active` and `manual` (each time `key` changes; a `pz.Trigger` given to `on=` uses it).

### `PROPERTIES`

The properties animations and transitions change: `opacity`, `x`, `y`, `scale`, `background`, `border_color`, `color`, `radius`, `border_width`, `glow` and `glow_color`.

### `WINDOW_TRANSITIONS`

Names for `Window.transition` (`fade`, `zoom`, `pop`, `slide_up`, `slide_down`, `slide_left`, `slide_right`) mapped to their `(opening, closing)` presets.

## Timeline animations

### `Clip`

```python
@dataclass
class Clip(name, length=None, tracks=(), calls=(), loop='none', description='')
```

A named timeline of `length` seconds with `tracks` and `calls` (see the module docs).

`loop` is `"none"` (plays once and holds the last frame), `"loop"` or
`"pingpong"`. `length` defaults to the time of the last key or call.

**Methods and properties**

#### `Clip.targets`

```python
Clip.targets  # property
```

The widget targets its tracks animate, in order.

#### `Clip.attributes`

```python
Clip.attributes  # property
```

The app attributes its tracks animate (`":score"` -> `"score"`).

#### `Clip.track`

```python
Clip.track(path)
```

The track with `path` (`None` when there is none).

#### `Clip.values`

```python
Clip.values(time, target=None)
```

`{path: value}` of the enabled tracks at `time` (only `target`'s, as `{property: value}`).

#### `Clip.with_track`

```python
Clip.with_track(track)
```

A copy with `track` added, or replacing the track with the same path.

#### `Clip.without_track`

```python
Clip.without_track(path)
```

A copy without the track `path`.

#### `Clip.with_key`

```python
Clip.with_key(path, time, value, easing=None)
```

A copy with a key at `time` on `path` (replacing one at the same time; adds the track).

#### `Clip.without_key`

```python
Clip.without_key(path, time)
```

A copy without the key at `time` on `path`.

#### `Clip.retarget`

```python
Clip.retarget(mapping, name=None)
```

A copy whose tracks animate other widgets: `clip.retarget({"card": "panel"})`.

#### `Clip.animation`

```python
Clip.animation(target, *, on='mount', **options)
```

`target`'s tracks as a `pz.Animation` (to play without a player, or `define_animation`).

#### `Clip.to_dict`

```python
Clip.to_dict()
```

JSON-ready data (`Clip.from_dict` reads it back).

#### `Clip.from_dict`

```python
@classmethod
Clip.from_dict(data)
```

Rebuilds a clip saved with `to_dict`.

### `Track`

```python
@dataclass
class Track(path, keys=(), easing='linear', interpolation='linear', enabled=True)
```

One property changing over time: `Track("card:opacity", {0: 0, 0.5: 1})`.

`keys` is `{time: value}`, a list of `(time, value)` or `(time, value, easing)`
tuples, or `Key` objects. `easing` is the default curve between keys (`"linear"`,
like Godot) and `interpolation="discrete"` holds each value until the next key.
`enabled=False` keeps a track in the clip without playing it.

**Methods and properties**

#### `Track.target`

```python
Track.target  # property
```

The widget target (`""` for an app attribute).

#### `Track.property`

```python
Track.property  # property
```

The property or attribute path it changes.

#### `Track.value_at`

```python
Track.value_at(time)
```

The track's value at `time` seconds (`None` when it has no keys).

#### `Track.with_keys`

```python
Track.with_keys(keys)
```

A copy with other keys.

#### `Track.to_dict`

```python
Track.to_dict()
```

JSON-ready data (`Track.from_dict` reads it back).

#### `Track.from_dict`

```python
@classmethod
Track.from_dict(data)
```

Rebuilds a track saved with `to_dict`.

### `Key`

```python
@dataclass
class Key(time, value, easing=None)
```

A value at a time on a track; `easing` is the curve to the next key (the track's when `None`).

**Methods and properties**

#### `Key.to_dict`

```python
Key.to_dict()
```

JSON-ready data (`Key.from_dict` reads it back).

#### `Key.from_dict`

```python
@classmethod
Key.from_dict(data)
```

Rebuilds a key saved with `to_dict`.

### `Call`

```python
@dataclass
class Call(time, method, args=())
```

A method called at `time` seconds: `Call(1.2, "play_sound", "ding")`.

`method` is the name of a method of the app (the player's `owner`) or a callable;
`args` are passed to it. What it returns (a `Command`, a message...) is handled
like a callback's.

**Methods and properties**

#### `Call.to_dict`

```python
Call.to_dict()
```

JSON-ready data (only calls to methods by name can be saved).

#### `Call.from_dict`

```python
@classmethod
Call.from_dict(data)
```

Rebuilds a call saved with `to_dict`.

### `AnimationPlayer`

```python
class AnimationPlayer
```

Plays `Clip`s on widgets and app state, with play, pause, seek, speed and a queue.

`sources` are clips, `AnimationLibrary` objects and `.pzanim` paths. Give widgets
their target with `widget.animate(player["card"])`; tracks of app attributes
(`":score"`) and `Call`s run on the player's `owner`, which is the app (or window)
that holds the player in an attribute, found automatically, or the one you pass.

- `autoplay`: the clip that plays when the player is created.
- `speed`: the playback speed of every clip (`play` multiplies it).
- `on_started(name)`/`on_finished(name)`: called when a clip starts and when it
  ends (never for looping clips); they may take no argument.
- `fps`: how often app attributes update while a clip with attribute tracks plays.

Events:

- `on_started(name)`: Called with the name of a clip when it starts.
- `on_finished(name)`: Called with the name of a clip when it ends (never for looping clips).

**Methods and properties**

#### `AnimationPlayer.add`

```python
AnimationPlayer.add(source, *, prefix=None)
```

Adds a clip, a library (its clips as `"name/clip"` when it has a name) or a `.pzanim` path.

#### `AnimationPlayer.remove`

```python
AnimationPlayer.remove(name)
```

Removes the clip `name` (stopping it when it is the current one).

#### `AnimationPlayer.names`

```python
AnimationPlayer.names  # property
```

The names of the clips it can play.

#### `AnimationPlayer.has`

```python
AnimationPlayer.has(name)
```

Whether it has a clip called `name`.

#### `AnimationPlayer.clip`

```python
AnimationPlayer.clip(name=None)
```

The clip named `name` (the current one by default).

#### `AnimationPlayer.target`

```python
AnimationPlayer.target(target, *, only=None)
```

Like `player[target]`; `only` keeps some properties (`("opacity", "x", "y")`), for example to move what sits inside an animated container along with it.

#### `AnimationPlayer.current`

```python
AnimationPlayer.current  # property
```

The clip playing or paused (`None` when stopped).

#### `AnimationPlayer.playing`

```python
AnimationPlayer.playing  # property
```

Whether time is moving.

#### `AnimationPlayer.paused`

```python
AnimationPlayer.paused  # property
```

Whether a clip is paused (stopped clips and finished ones aren't).

#### `AnimationPlayer.finished`

```python
AnimationPlayer.finished  # property
```

Whether the current clip reached its end.

#### `AnimationPlayer.length`

```python
AnimationPlayer.length  # property
```

The length of the current clip in seconds (0 when none).

#### `AnimationPlayer.position`

```python
AnimationPlayer.position  # property
```

Seconds into the current clip.

#### `AnimationPlayer.queued`

```python
AnimationPlayer.queued  # property
```

The clips that play after the current one, in order.

#### `AnimationPlayer.value`

```python
AnimationPlayer.value(path)
```

The value the current clip gives `path` (`"card:opacity"`, `":score"`) right now.

#### `AnimationPlayer.play`

```python
AnimationPlayer.play(name=None, *, speed=1.0, backwards=False, from_end=False, restart=False)
```

Plays `name` (the current or paused clip by default) from where it is.

#### `AnimationPlayer.play_backwards`

```python
AnimationPlayer.play_backwards(name=None, *, speed=1.0)
```

Plays `name` in reverse from its end (or the current clip from where it is).

#### `AnimationPlayer.pause`

```python
AnimationPlayer.pause()
```

Stops time where it is (`play()` or `resume()` goes on).

#### `AnimationPlayer.resume`

```python
AnimationPlayer.resume()
```

Goes on from where the clip was paused.

#### `AnimationPlayer.toggle`

```python
AnimationPlayer.toggle()
```

Pauses when playing, plays otherwise.

#### `AnimationPlayer.stop`

```python
AnimationPlayer.stop(*, reset=False)
```

Stops at the start of the clip (showing its first frame); `reset` lets widgets go back to their own values and forgets the clip. Clears the queue.

#### `AnimationPlayer.seek`

```python
AnimationPlayer.seek(seconds)
```

Jumps to `seconds` into the current clip (calls on the way don't run).

#### `AnimationPlayer.advance`

```python
AnimationPlayer.advance(seconds)
```

Moves the current clip `seconds` forward (calls run, state updates), like Godot's `advance`.

#### `AnimationPlayer.queue`

```python
AnimationPlayer.queue(name)
```

Plays `name` after the current clip ends (or now when nothing plays).

#### `AnimationPlayer.clear_queue`

```python
AnimationPlayer.clear_queue()
```

Forgets the queued clips.

#### `AnimationPlayer.subscriptions`

```python
AnimationPlayer.subscriptions()
```

What keeps the player's calls, attribute tracks and queue going (added for you when the player is an attribute of the app or a window).

### `AnimationLibrary`

```python
class AnimationLibrary
```

Named clips that are saved together in a `.pzanim` file and reused.

`AnimationLibrary([intro, idle], name="ui")`; `lib["intro"]`, `lib.add(clip)`,
`lib.remove("idle")`, `lib.save("ui.pzanim")` and `AnimationLibrary.load(path)`.
A player given a library with a `name` calls its clips `"ui/intro"`, like Godot.

**Methods and properties**

#### `AnimationLibrary.add`

```python
AnimationLibrary.add(clip)
```

Adds `clip` (replacing one with its name) and returns it.

#### `AnimationLibrary.remove`

```python
AnimationLibrary.remove(name)
```

Removes the clip `name` (nothing happens when there is none).

#### `AnimationLibrary.rename`

```python
AnimationLibrary.rename(old, new)
```

Renames the clip `old` to `new` and returns it.

#### `AnimationLibrary.names`

```python
AnimationLibrary.names  # property
```

The names of its clips, in order.

#### `AnimationLibrary.to_dict`

```python
AnimationLibrary.to_dict()
```

The `.pzanim` data (`AnimationLibrary.from_dict` reads it back).

#### `AnimationLibrary.from_dict`

```python
@classmethod
AnimationLibrary.from_dict(data)
```

Rebuilds a library from `.pzanim` data.

#### `AnimationLibrary.save`

```python
AnimationLibrary.save(path)
```

Writes the library as JSON (a `.pzanim` file) and returns the path.

#### `AnimationLibrary.load`

```python
@classmethod
AnimationLibrary.load(path)
```

Reads a `.pzanim` file (raises `ValueError` when it isn't one).

### `load_animations`

```python
load_animations(path)
```

The library saved in a `.pzanim` file.

## Large data

### `virtual_column`

```python
virtual_column(count, item, *, item_height, spacing=0.0, overscan=4, width=None)
```

A column of `count` rows of the same height that only builds the rows in view: `item(index)` is called when row `index` scrolls into view, and rows that leave it are dropped. A column of a million rows costs the same as one of fifty. Put it in a `scrollable` (it virtualizes against the visible area of the closest one, or the window).

| Parameter | Description |
| --- | --- |
| `count` | Number of rows. |
| `item` | Function that receives a row index and returns its widget. |
| `item_height` | Height of every row, in pixels. |
| `spacing` | Space between rows, in pixels. |
| `overscan` | Extra rows built above and below the visible ones, so fast scrolling shows no gaps. |
| `width` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |

```python
rows = load_logs()          # a list with 500 000 entries

pz.scrollable(
    pz.virtual_column(len(rows), lambda i: pz.text(rows[i]), item_height=20),
    id="logs", height="fill",
)
```

### `memo`

```python
memo(function=None, *, maxsize=64)
```

Decorator that caches what a view function returns by its arguments, so the next `view()` reuses the same widget tree while they don't change. Pass everything the subtree depends on as arguments. Lists, dicts and sets compare by contents, other unhashable objects by identity; the current theme and language are always part of the key. `function.cache_clear()` empties its cache.

| Parameter | Description |
| --- | --- |
| `function` | The function to memoize (when used as `@pz.memo`). |
| `maxsize` | How many results to keep per function (least recently used are dropped). |

```python
@pz.memo
def sidebar(files: tuple, selected: str):
    return pz.column([ui.list_item(f, selected=f == selected) for f in files])
```

### `clear_memos`

```python
clear_memos()
```

Empties the cache of every `@pz.memo` function.

### `memo_stats`

```python
memo_stats()
```

Returns `{"hits": n, "misses": m}`: how many calls of memoized functions were answered from the cache and how many built their result.