# Themes

> API reference for pyzed Theme: the built-in themes, color tokens, deriving custom themes and color utilities for Python GUIs.

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

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

See the [theming](https://albakore.github.io/pyzed/theming/themes/) guide for the list of tokens and how to create your own.

## Theme

### `Theme`

A theme: an immutable dataclass with color tokens (surfaces, borders, elements, text, status, editor, syntax, collaborator and ANSI colors) and metrics (`radius`, `radius_sm`, `ui_font_size`, `buffer_font_size`). The `is_dark` property tells whether it is dark.

**Methods and properties**

#### `Theme.is_dark`

```python
Theme.is_dark  # property
```

Whether the theme's appearance is dark.

### `derive`

```python
derive(self, **changes)
```

Returns a copy with some tokens changed. The `syntax` and `ansi` dicts are merged instead of replaced.

| Parameter | Description |
| --- | --- |
| `changes` | Tokens to change. |

```python
ocean = pz.themes.ONE_DARK.derive(name="Ocean", accent="#4fb3ff", syntax={"keyword": "#ff79c6"})
```

### `color`

```python
color(self, name)
```

Resolves a token (`"accent"`, `"text_muted"`…) to its color. Hex colors and `"transparent"` pass through unchanged.

| Parameter | Description |
| --- | --- |
| `name` | Token or color. |

### `tokens`

```python
tokens(self)
```

All tokens as a dict.

### `syntax_scopes`

```python
syntax_scopes(self)
```

Maps the theme's syntax tokens to TextMate scopes for the highlighter.

### `palette`

```python
palette(self)
```

The base palette passed to Iced for its internal styles. Internal use.

### `with_accent`

```python
with_accent(self, accent)
```

A copy with a different accent color and everything that depends on it (focus, selection, links, primary buttons, text on accent).

| Parameter | Description |
| --- | --- |
| `accent` | The color. |

### `generate`

```python
generate(
    name,
    *,
    background,
    text,
    accent,
    appearance=None,
    error=None,
    warning=None,
    success=None,
    syntax=None,
    radius=6.0,
)
```

Creates a complete theme from a few colors. Surfaces, borders, hover states and muted text are mixed from `background` and `text`; the appearance is inferred from the background brightness if not given.

| Parameter | Description |
| --- | --- |
| `name` | Name. |
| `background` | Editor/background color. |
| `text` | Text color. |
| `accent` | Accent color. |
| `appearance` | `"dark"` or `"light"`. |
| `error` | Error color. |
| `warning` | Warning color. |
| `success` | Success color. |
| `syntax` | Extra syntax colors. |
| `radius` | Corner radius. |

```python
pz.Theme.generate("Custom", background="#1b1d23", text="#e6e6e6", accent="#ff8a65")
```

### `from_zed`

```python
from_zed(source, name=None)
```

Reads a theme from a Zed theme family file (`.json`) or a dict. A family usually has several (Ayu Dark/Light/Mirage); `name` picks one (the first by default).

| Parameter | Description |
| --- | --- |
| `source` | Path, JSON text or dict. |
| `name` | Name of the theme within the family. |

### `to_dict`

```python
to_dict(self)
```

A JSON-ready dict; `Theme.from_dict` reads it back.

### `from_dict`

```python
from_dict(data, *, base=None)
```

Creates a theme from `to_dict`. Missing tokens come from `base` (One Dark or One Light depending on `appearance`).

| Parameter | Description |
| --- | --- |
| `data` | The tokens. |
| `base` | Base theme. |

### `save`

```python
save(self, path)
```

Saves the theme as JSON (Pyzed's own format).

| Parameter | Description |
| --- | --- |
| `path` | File path. |

### `load`

```python
load(path)
```

Reads a theme written with `save` (for Zed themes use `from_zed`).

| Parameter | Description |
| --- | --- |
| `path` | File path. |

## Built-in themes

### `themes`

Namespace with the built-in themes (the One, Ayu and Gruvbox families) and the theme registry. Built-in themes are also available as attributes: `themes.ONE_DARK`, `themes.ONE_LIGHT`, `themes.AYU_DARK`, `themes.AYU_LIGHT`, `themes.AYU_MIRAGE`, `themes.GRUVBOX_DARK`, `themes.GRUVBOX_LIGHT`…

### `all`

```python
all()
```

List of all built-in themes.

### `names`

```python
names()
```

Names of all registered themes.

### `get`

```python
get(name)
```

Looks up a theme by name (case-insensitive). Raises `KeyError` if it doesn't exist.

| Parameter | Description |
| --- | --- |
| `name` | Name. |

### `register`

```python
register(theme)
```

Adds (or replaces) a theme so it can be used by name.

| Parameter | Description |
| --- | --- |
| `theme` | The theme. |

### `load_zed`

```python
load_zed(source)
```

Loads and registers every theme in a Zed family file.

| Parameter | Description |
| --- | --- |
| `source` | Path, JSON text or dict. |

### `auto`

```python
auto(light='One Light', dark='One Dark')
```

A theme that follows the system's light/dark mode.

| Parameter | Description |
| --- | --- |
| `light` | Theme (or name) for light mode. |
| `dark` | Theme (or name) for dark mode. |

### `AutoTheme`

What `themes.auto` returns: a `(light, dark)` pair. `pick(dark)` returns the right one.

**Methods and properties**

#### `AutoTheme.pick`

```python
AutoTheme.pick(dark)
```

Returns the dark theme when `dark` is true, else the light one.

## Utilities (pyzed.theme)

### `current`

```python
current()
```

The theme components use when no `theme=` is passed.

### `use`

```python
use(theme)
```

Changes the current theme. `App` does this before every `view()`, so you normally don't need it.

| Parameter | Description |
| --- | --- |
| `theme` | The theme. |

### `alpha`

```python
alpha(color, value)
```

Returns `color` with its opacity multiplied by `value`.

| Parameter | Description |
| --- | --- |
| `color` | Hex color. |
| `value` | Factor from 0 to 1. |

```python
pz.theme.alpha("#74ade8", 0.2)  # "#74ade833"
```

### `mix`

```python
mix(a, b, amount=0.5)
```

Mixes two colors: `amount=0` is `a` and `amount=1` is `b`.

| Parameter | Description |
| --- | --- |
| `a` | First color. |
| `b` | Second color. |
| `amount` | Proportion of `b`. |

### `resolve`

```python
resolve(value, *, dark=True)
```

Turns an `App.theme` value (theme, name, `AutoTheme` or `None`) into a `Theme`.

| Parameter | Description |
| --- | --- |
| `value` | The value. |
| `dark` | Whether the system is in dark mode. |

### `lighten`

```python
lighten(color, amount=0.1)
```

Lightens a color.

| Parameter | Description |
| --- | --- |
| `color` | Hex color. |
| `amount` | Amount from 0 to 1. |

### `darken`

```python
darken(color, amount=0.1)
```

Darkens a color.

| Parameter | Description |
| --- | --- |
| `color` | Hex color. |
| `amount` | Amount from 0 to 1. |

### `luminance`

```python
luminance(color)
```

Relative luminance (WCAG) of a color, from 0 to 1.

| Parameter | Description |
| --- | --- |
| `color` | Hex color. |

### `contrast`

```python
contrast(a, b)
```

WCAG contrast ratio between two colors (1 to 21).

| Parameter | Description |
| --- | --- |
| `a` | First color. |
| `b` | Second color. |

### `readable_on`

```python
readable_on(background, light='#fafafa', dark='#1c2025')
```

Returns `light` or `dark`, whichever has more contrast on `background`.

| Parameter | Description |
| --- | --- |
| `background` | Background color. |
| `light` | Light text. |
| `dark` | Dark text. |