Icon (Core)

ttkbootstrap_icons.icon.Icon

Bases: StatefulIconMixin, ABC

Base class for rendered TTF-based icons (PIL -> PhotoImage).

Performance features

• Class-level caches for rendered images and PIL fonts.
• Class-level cache for transparent placeholders.
• Reuses a temporary font file per (provider, style).
• slots to reduce per-instance overhead.

__slots__ = ('name', 'size', 'color', '_img', '_font_path', '_icon_set_id') class-attribute instance-attribute

_cache = {} class-attribute

_current_font_path = None class-attribute

_font_cache = {} class-attribute

_font_path = Icon._current_font_path instance-attribute

_fontfile_cache = {} class-attribute

_icon_map = {} class-attribute

_icon_map_cache = {} class-attribute

_icon_set = '' class-attribute

_icon_set_id = Icon._icon_set instance-attribute

_img = self._render() instance-attribute

_initialized = False class-attribute

_is_regenerating = False class-attribute

_original_image = None class-attribute instance-attribute

_render_params_cache = {} class-attribute

_transparent_cache = {} class-attribute

_widget_mappings = {} class-attribute

color = color instance-attribute

image property

name = name instance-attribute

size = size instance-attribute

__init__(name, size=24, color='black')

Create a new icon.

Parameters:

Name	Type	Description	Default
name	str	Resolved icon key in the icon map.	required
size	int	Pixel size.	24
color	str	Foreground color.	'black'

__str__()

_button_color_for_state(style, parent_style, state)

Resolve the parent style's foreground color for a given state.

Parameters:

Name	Type	Description	Default
style	Style	ttk Style instance.	required
parent_style	str	Parent style name (e.g., 'my.TButton').	required
state	str	State flag to resolve (e.g., 'hover').	required

Returns:

Type	Description
Optional[str]	The resolved color string or None if not available.

_configure(font_path, icon_map) classmethod

_ensure_original_image()

Ensure the untinted base image is cached for the '' fallback.

Notes

Uses the instance's own .image to avoid re-instantiation or recursion during host initialization.

_get_transparent(size) classmethod

_on_theme_changed(event) classmethod

Handle <> event by regenerating all mapped icons.

_parse_statespec(style, parent_style, statespec)

Parse the state spec into (state, icon_name, color) triples.

If statespec is not provided, triples are derived from the parent's foreground map using the base icon.

Parameters:

Name	Type	Description	Default
style	Style	ttk Style instance.	required
parent_style	str	Parent style name to read maps from.	required
statespec	Optional[list[IconStateSpec]]	Optional list describing per-state overrides. Each item is a (state, spec) pair where spec is either a color string or a dict with keys name and/or color.	required

Returns:

Type	Description
list[tuple[str, str, Optional[str]]]	A list of triples (state, icon_name, color_or_None). If color is
list[tuple[str, str, Optional[str]]]	None, the caller will resolve to the parent's state foreground.

_render()

Render the icon as a PhotoImage, using PIL and caching the result.

_render_icon(name, size, color)

Render a Tk-compatible image for (name, size, color).

By default, this constructs a new instance of type(self) with the provided (name, size, color) and returns its .image. If your host class requires a different constructor or you want a more direct path, override this method.

Parameters:

Name	Type	Description	Default
name	str	Icon name to render.	required
size	int	Icon size in pixels.	required
color	Optional[str]	Optional color to tint the icon. If None, render untinted.	required

Returns:

Type	Description
object	A Tk-compatible image object (e.g., PhotoImage).

_slug(token) staticmethod

Return a style-safe token by replacing unsupported characters.

Parameters:

Name	Type	Description	Default
token	str	Arbitrary token (e.g., icon name).	required

Returns:

Type	Description
str	A string containing only alphanumerics, '-' or '_'.

_state_tuple(state) staticmethod

Convert a state string into a ttk lookup tuple.

Parameters:

Name	Type	Description	Default
state	str	Single state flag (e.g., 'hover', 'pressed').	required

Returns:

Type	Description
tuple[str, ...]	A one-element tuple containing state.

cleanup() classmethod

Remove all temporary font files and reset internal icon state.

initialize_with_provider(provider, style=None) classmethod

Initialize icon rendering using an external provider.

map(widget, *, subclass=None, statespec=None, mode='merge')

Apply per-state images to a child style derived from the widget's style.

This computes per-state images from statespec (or the parent's foreground map when statespec is omitted), generates a child style name, and maps the image option accordingly. The empty-state ('') fallback is always set to the instance's original untinted image.

Parameters:

Name	Type	Description	Default
widget	Widget	ttk widget to style (e.g., ttk.Button).	required
subclass	Optional[str]	Optional child style prefix. If omitted, the name is generated by concatenating the unique icon names used (including the base) and appending the size, e.g., "house-house-fill-16.my.TButton".	None
statespec	Optional[list[IconStateSpec]]	Optional list of per-state overrides. Each item is a (state, spec) pair where spec is a color string or a dict with name and/or color. If color is omitted, the icon color follows the parent's foreground for that state.	None
mode	StateMapMode	Merge strategy for the child style's image map. * "merge" (default): Read the existing image map for the same child style, overwrite incoming states, preserve order of existing entries, and append new states. * "replace": Ignore any existing map and apply only the provided states (plus the fallback).	'merge'

Returns:

Type	Description
None	None

ttkbootstrap_icons.icon.create_transparent_icon(size=16)

Return or create a transparent placeholder image of given size.