Themes

See the theming 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

Theme.is_dark  # property

Whether the theme’s appearance is dark.

derive

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.

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

color

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

tokens(self)

All tokens as a dict.

syntax_scopes

syntax_scopes(self)

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

palette

palette(self)

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

with_accent

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

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.

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

from_zed

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

to_dict(self)

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

from_dict

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

save(self, path)

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

Parameter	Description
path	File path.

load

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

all()

List of all built-in themes.

names

names()

Names of all registered themes.

get

get(name)

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

Parameter	Description
name	Name.

register

register(theme)

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

Parameter	Description
theme	The theme.

load_zed

load_zed(source)

Loads and registers every theme in a Zed family file.

Parameter	Description
source	Path, JSON text or dict.

auto

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

AutoTheme.pick(dark)

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

Utilities (pyzed.theme)

current

current()

The theme components use when no theme= is passed.

use

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

alpha(color, value)

Returns color with its opacity multiplied by value.

Parameter	Description
color	Hex color.
value	Factor from 0 to 1.

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

mix

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

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

lighten(color, amount=0.1)

Lightens a color.

Parameter	Description
color	Hex color.
amount	Amount from 0 to 1.

darken

darken(color, amount=0.1)

Darkens a color.

Parameter	Description
color	Hex color.
amount	Amount from 0 to 1.

luminance

luminance(color)

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

Parameter	Description
color	Hex color.

contrast

contrast(a, b)

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

Parameter	Description
a	First color.
b	Second color.

readable_on

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.