Theming#

A theme is a named color scheme the engine turns into widget styles. Theme declares a theme family in code from a handful of anchor colors; ThemeDefinition is the per-mode container the engine consumes; and Colors is the resolved palette you read off the active theme (through Style.colors). install_legacy_themes brings the pre-2.0 theme names back for migration. The Theming & Colors guide shows them in use.

Declaring a theme#

class Theme(name, primary=None, success=None, info=None, warning=None, danger=None, secondary=None, neutral='#adb5bd', light=None, dark=None)#

Bases: object

A semantic-anchor color theme family declared in code.

Declare the accent colors once (as the [500] midpoint of each ramp) plus a light and/or dark {background, foreground} block; the family generates a well-contrasted ThemeDefinition per mode (<name>-light / <name>-dark). The per-mode ramp step for solids, borders, and inputs is chosen automatically – there is no per-mode shade boilerplate.

Parameters:

name (str) – Family name; generated variants are <name>-light / <name>-dark.
primary (str) – Accent [500] anchor colors (hex).
success (str) – Accent [500] anchor colors (hex).
info (str) – Accent [500] anchor colors (hex).
warning (str) – Accent [500] anchor colors (hex).
danger (str) – Accent [500] anchor colors (hex).
secondary (str) – Optional colored secondary accent (hex). When omitted, secondary derives from the neutral ramp.
neutral (str) – Gray base for the neutral ramp (secondary, the light/dark accents).
light (dict) – {'background': ..., 'foreground': ...} for that variant, or None to skip it.
dark (dict) – {'background': ..., 'foreground': ...} for that variant, or None to skip it.

classmethod from_existing(base, *, name, **overrides)#

Derive a new family from an existing Theme, overriding some tokens.

Every token not overridden is inherited from base, so a built-in can be re-branded by changing just its primary (and anything else).

Parameters:

base (Theme)
name (str)

Return type:

Theme

register()#

Register the generated variants on the live Style singleton.

Returns this theme so theme = Theme(...).register() reads cleanly. Raises RuntimeError if no Style has been created yet.

to_definitions()#

Return the generated per-mode ThemeDefinition objects (light, then dark).

A family that declares only one block yields a single definition.

danger: str = None#: Accent [500] anchor color (hex).

dark: dict = None#: {'background': ..., 'foreground': ...} for the dark variant, or None to skip it.

info: str = None#: Accent [500] anchor color (hex).

light: dict = None#: {'background': ..., 'foreground': ...} for the light variant, or None to skip it.

name: str#: Family name; generated variants are <name>-light / <name>-dark.

neutral: str = '#adb5bd'#: Gray base for the neutral ramp (secondary, the light/dark accents).

primary: str = None#: Accent [500] anchor color (hex).

secondary: str = None#: Optional colored secondary accent (hex); derives from the neutral ramp when omitted.

success: str = None#: Accent [500] anchor color (hex).

warning: str = None#: Accent [500] anchor color (hex).

class ThemeDefinition(name, colors, mode='light', **kwargs)#

Bases: object

Encapsulates the name, color palette, and metadata for a ttkbootstrap theme.

A ThemeDefinition is a lightweight container that pairs a theme name with its Colors object and whether it is a light or dark theme. The Style engine consumes ThemeDefinition instances to build widget styles and images for the active theme.

Parameters:

name (str) – The name of the theme.
colors (Colors or dict) – A Colors instance or a dict of color values.
mode (str) – Specifies whether the theme is light or dark.

property type#: Deprecated alias for mode (removed in 3.0).

The color palette#

class Colors(primary, secondary, success, info, warning, danger, light, dark, bg, fg, selectbg, selectfg, border, inputfg, inputbg, active)#

Bases: object

A class that defines the color scheme for a theme as well as provides several static methods for manipulating colors.

A Colors object is attached to a ThemeDefinition and can also be accessed through the Style.colors property for the current theme.

This class is an iterator over the main style color labels (primary, secondary, success, info, warning, danger, light, dark); label_iter iterates over every theme color label.

Parameters:

primary (str) – The primary theme color; used by default for all widgets.
secondary (str) – An accent color; commonly of a grey hue.
success (str) – An accent color; commonly of a green hue.
info (str) – An accent color; commonly of a blue hue.
warning (str) – An accent color; commonly of an orange hue.
danger (str) – An accent color; commonly of a red hue.
light (str) – An accent color.
dark (str) – An accent color.
bg (str) – Background color.
fg (str) – Default text color.
selectfg (str) – The color of selected text.
selectbg (str) – The background color of selected text.
border (str) – The color used for widget borders.
inputfg (str) – The text color for input widgets.
inputbg (str) – The text background color for input widgets.
active (str) – An accent color.

static hex_to_rgb(color)#

Convert hexadecimal color to rgb color value

Parameters:: color (str) – A hexadecimal color value
Returns:: tuple[float, float, float] – The rgb color value, each channel normalized to 0-1.

static label_iter()#

Iterate over all color label properties in the Color class

Returns:: iter – An iterator for color label names

static make_transparent(alpha, foreground, background='#ffffff')#

Simulate color transparency.

Parameters:

alpha (float) – The amount of transparency; a number between 0 and 1.
foreground (str) – The foreground color.
background (str) – The background color.

Returns:

str – A hexadecimal color representing the “transparent” version of the foreground color against the background color.

static rgb_to_hex(r, g, b)#

Convert rgb to hexadecimal color value

Parameters:

r (int) – red
g (int) – green
b (int) – blue

Returns:

str – A hexadecimal color value

static rgb_to_hsv(r, g, b)#

Convert an rgb to hsv color value.

Parameters:

r (float) – red
g (float) – green
b (float) – blue

Returns:

tuple[float, float, float] – The hsv color value.

static update_hsv(color, hd=0, sd=0, vd=0)#

Modify the hue, saturation, and/or value of a given hex color value by specifying the delta.

Parameters:

color (str) – A hexadecimal color value to adjust.
hd (float) – % change in hue, the hue delta.
sd (float) – % change in saturation, the saturation delta.
vd (float) – % change in value, the value delta.

Returns:

str – The resulting hexadecimal color value

get(color_label)#

Lookup a color value from the color name

Parameters:: color_label (str) – A color label corresponding to a class property
Returns:: str – A hexadecimal color value.

get_contrast_ration(lum1, lum2)#

Calculate the contrast ratio between two luminance values.

Parameters:

lum1 (float) – The first luminance value.
lum2 (float) – The second luminance value.

Returns:

float – The contrast ratio.

get_foreground(color_label)#

Return the appropriate foreground color for the specified color_label.

Parameters:: color_label (str) – A color label corresponding to a class property
Returns:: str – A hexadecimal color value for the foreground color.
Raises:: TypeError – If the color_label is not a valid color property.

get_luminance(color)#

Calculate the luminance of a color.

Parameters:: color (str) – A hexadecimal color value.
Returns:: float – The luminance value of the color.

ramp(color_label)#

Return the full immutable 50-950 tint/shade ramp for a color role.

The role’s current value is treated as the [500] anchor. Equivalent to reading each stop off the addressable color (self.get(label)[stop]) but returns the whole mapping at once.

Parameters:: color_label (str) – A color label corresponding to a class property.
Returns:: Mapping[int, str] – An immutable mapping of ramp stop (50-950) to hex color.
Return type:: Mapping[int, str]

set(color_label, color_value)#

Set a color property value. This does not update any existing widgets. Can also be used to create on-demand color properties that can be used in your program after creation.

Parameters:

color_label (str) – The name of the color to be set (key)
color_value (str) – A hexadecimal color value

Legacy themes#

install_legacy_themes(style=None)#

Register the pre-2.0 theme names on the live Style (opt-in).

Each legacy theme is adapted through theme_from_legacy_dict (authored identity preserved, plumbing regenerated). Already-registered names are skipped, so calling this more than once is safe. Emits a one-time DeprecationWarning: the legacy names are a migration convenience, not the 2.0 catalog.

Parameters:: style – The Style to register onto; defaults to the live singleton.
Return type:: None

Theming#

Declaring a theme#

The color palette#

Legacy themes#

See also#