# Slider

> Pick a number in a range by dragging. A native Pyzed component for Python desktop GUIs, with a live preview, code examples and its API.

Source: https://albakore.github.io/pyzed/library/slider/

:::tip[In plain words]
A bar with a knob you drag to pick an amount, like a volume control.
:::

A themed slider between `min` and `max` (0 to 1 by default) that moves in `step` increments. `on_change` receives the new value while dragging.

`ui.slider` · Category: [Forms](https://albakore.github.io/pyzed/library/#forms) · [Full reference →](https://albakore.github.io/pyzed/reference/ui/#slider)

**Code:**

```python
pz.column([
    ui.slider(0.35, on_change),
    ui.slider(70, on_change, min=0, max=100, step=1),
], spacing=18, width=360)
```

## When to use

- For values where the exact number matters less than the feel: volume, opacity, zoom.
- When users need to type an exact value, use a [Number field](https://albakore.github.io/pyzed/library/number-field/).

## Usage

```python
import pyzed as pz
from pyzed import ui

class Player(pz.App):
    def __init__(self):
        self.volume = 70

    def view(self):
        return pz.row([
            ui.slider(self.volume, lambda v: setattr(self, "volume", v), min=0, max=100, step=1),
            ui.label(f"{self.volume:.0f}%"),
        ], spacing=12, align="center")
```

## Variants

:::note[About these captures]
Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site's theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open **Code** under a capture to see the snippet that draws it; free names such as `on_save` stand for your own callbacks.
:::

### Value

```python
ui.slider(0.0, on_change, width=240)
```

```python
ui.slider(0.35, on_change, width=240)
```

```python
ui.slider(1.0, on_change, width=240)
```

### Range and step

```python
ui.slider(70, on_change, min=0, max=100, step=1, width=240)
```

```python
pz.column([ui.slider(40, on_change, min=0, max=100, step=10, width=240),
           ui.muted("40 %")], spacing=6, align="center")
```

### States and events

`on_release` runs when the drag ends: save or apply there instead of on every move.

```python
ui.slider(70, on_change, min=0, max=100, step=1, show_value=True, width=240)
```

```python
ui.slider(0.35, on_change, show_value="{:.0%}", width=240)
```

```python
ui.slider(6, on_change, min=0, max=10, step=1, vertical=True, height=110, show_value=True)
```

```python
ui.slider(0.6, on_change, disabled=True, width=240)
```

### Base widget

The `pz.*` widget underneath: no theme, every color and size is yours.

```python
pz.slider(0, 100, 60, on_change=on_change, width=240, accent="#e5c07b", knob_color="#ffffff")
```

```python
pz.vertical_slider(0, 100, 60, on_change=on_change, height=120, accent="#56b6c2")
```

## Events

Slider has **2 events of its own**, listed below. Like every widget it also has the **18 common events** (`click`, `double_click`, `right_click`, `mouse_enter`, `drag`, `key_down`, `resize`…), attached with `.on(...)`: see [Events](https://albakore.github.io/pyzed/guides/events/) and [Events of every component](https://albakore.github.io/pyzed/library/events/).

| Event | Of | Handler gets | When |
| --- | --- | --- | --- |
| `on_change` | `ui.slider`, `pz.slider` | `(value)` | Callable that receives the new value. |
| `on_release` | `ui.slider`, `pz.slider` | `()` | Sent when the drag ends (save or apply there). |

**Handler gets** is what Pyzed passes to your callable: `()` means nothing. Any handler can also be a message (a value that is not callable), which goes to `update()`.

### Handling the events

The same events written three ways. **Imperative**: methods of the app change `self`. **Declarative**: the handlers produce messages and one `update()` decides. **Functional**: a pure function draws an immutable state and asks for changes with `set_state(...)`. See [Imperative, declarative and functional](https://albakore.github.io/pyzed/guides/code-styles/).

**Imperative:**

```python
class Player(pz.App):
    def __init__(self):
        self.volume = 70
        self.saved = 70

    def view(self):
        return pz.row([
            ui.slider(self.volume, lambda v: setattr(self, "volume", v),   # on_change: while dragging
                      min=0, max=100, step=1,
                      on_release=lambda: setattr(self, "saved", self.volume)),  # on_release: once
            ui.label(f"{self.volume:.0f}% (saved {self.saved:.0f}%)"),
        ], spacing=12, align="center", width=420)
```

**Declarative:**

```python
from dataclasses import dataclass

@dataclass
class Volume:
    value: float

class Player(pz.App):
    volume = 70
    saved = 70

    def update(self, message):
        match message:
            case Volume(value):
                self.volume = value
            case "save":
                self.saved = self.volume

    def view(self):
        return ui.slider(self.volume, Volume, min=0, max=100, step=1, on_release="save")
```

**Functional:**

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class State:
    volume: float = 70

def view(state, set_state):
    return pz.row([
        ui.slider(state.volume, lambda v: set_state(volume=v), min=0, max=100, step=1),
        ui.label(f"{state.volume:.0f}%"),
    ], spacing=12, align="center", width=420)
```

## Tips

:::tip
Once clicked or reached with Tab it has the keyboard focus: the arrows move it one `step`, with Shift (or Page Up/Down) ten, and Home/End jump to `min`/`max`.
:::

## Properties and API

### `ui.slider`

```python
slider(
    value,
    on_change=None,
    *,
    min=0.0,
    max=1.0,
    step=0.01,
    on_release=None,
    vertical=False,
    width=None,
    height=None,
    disabled=False,
    show_value=False,
    id=None,
    theme=None,
)
```

A slider.

| Property | Default | Description |
| --- | --- | --- |
| `value` | *required* | Current value. |
| `min` | `0.0` | Minimum. |
| `max` | `1.0` | Maximum. |
| `step` | `0.01` | Step. |
| `vertical` | `False` | Stands it up. |
| `width` | `None` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | `None` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `disabled` | `False` | Greys it out. |
| `show_value` | `False` | Shows the number next to it: `True`, or a format such as `"{:.0%}"`. |
| `id` | `None` | Stable identifier used to focus or scroll it with a `Command`. |
| `theme` | `None` | Theme to use instead of the current one (`pyzed.theme.current()`). |

Events: `on_change`, `on_release` ([events](#events)).

[Full reference →](https://albakore.github.io/pyzed/reference/ui/#slider)

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

| Property | Default | Description |
| --- | --- | --- |
| `min` | *required* | Minimum. |
| `max` | *required* | Maximum. |
| `value` | *required* | Current value. |
| `step` | `1.0` | Step. |
| `width` | `None` | Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `height` | `None` | Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion). |
| `vertical` | `False` | Vertical orientation. |
| `accent` | `None` | Accent color (active part). |
| `bg` | `None` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `knob_color` | `None` | Knob color. |
| `border_color` | `None` | Border color. |

Events: `on_change`, `on_release` ([events](#events)).

[Full reference →](https://albakore.github.io/pyzed/reference/widgets/#slider)

### `pz.vertical_slider`

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

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

| Property | Default | Description |
| --- | --- | --- |
| `min` | *required* | Minimum. |
| `max` | *required* | Maximum. |
| `value` | *required* | Current value. |
| `**kwargs` | — | Same as `slider`. |

[Full reference →](https://albakore.github.io/pyzed/reference/widgets/#vertical_slider)

## Related

- [Number field](https://albakore.github.io/pyzed/library/number-field/): A number with −/+ buttons, limits, step and suffix.
- [Progress](https://albakore.github.io/pyzed/library/progress/): A thin progress bar in a semantic color.