ttkbootstrap Documentation

The new theme model features a curated catalog of approximately 30 light and dark themes organized into families.

Bootstack Families: bootstrap, pydata, nord, solarized, catppuccin, gruvbox, dracula, tokyo-night, one, everforest. Migrated Families: vapor, minty, pulse, united, sandstone (these include both light and dark variants).

ttkbootstrap 2.0 uses three distinct measurement units to handle scaling and high-DPI displays correctly. Understanding these is critical when defining custom styles or working with assets:

1. Logical UI units (lu): These are theme-authored dimensions at baseline density (e.g., padding, borders, radii, progressbar thickness). At 100% scaling, 1 lu = 1 px. These are NOT Tk points; font point sizes are handled separately by Tk.
2. Physical pixels (px): Integer dimensions used for Pillow, PhotoImage, canvas coordinates, and pixel-valued style options. Warning: A value already in physical pixels must never be passed through scale_size again.
3. Source-image pixels (spx): Coordinates within a source PNG/asset. These define the bitmap's resolution but do not define the UI widget size. Assets carry an explicit logical target size to map spx to lu.

ttkbootstrap provides several tools to handle translations for built-in strings like dialog buttons and date names using Tk's message catalog:

• L(): Performs a lookup for a translated string.
• set_locale(): Switches the active locale for the application.
• LocaleVar: A specialized variable that automatically re-translates its content whenever the locale changes.
• MessageCatalog: A lower-level API for managing the message catalog directly.

The toolkit is designed as a set of thin helpers, not a Domain Specific Language (DSL).

Key architectural principles:

• Orthogonality: Each helper performs a single mechanical job and composes with raw ttk calls.
• Key Derivation: Cache keys are computed from the inputs that determine pixels. It is impossible to write a draw whose key omits a color it uses, as the key is built internally from the recipe or the *key_parts provided in the image() call.
• No Internal State: The toolkit adds no runtime state of its own beyond the existing Style._image_cache.

In ttkbootstrap 2.0, checkbuttons, radiobuttons, and switches use a flat, single-glyph aesthetic. Instead of two-tone filled looks, they use one glyph per state rendered in the state color.

For glyphs with interior marks (like -fill variants), the mark is a transparent knockout that shows the widget background through it. This ensures the indicators are automatically theme-adaptive (e.g., a primary square with a light-background check on light themes, and a dark-background check on dark themes).

ttkbootstrap uses the Bootstrap Icons font to render glyph-shaped widget assets (such as checkbutton/radiobutton/switch indicators, combobox/spinbox arrows, date-entry buttons, and sizegrips).

Because the icons are bundled directly within the package, there are no extra pip dependencies required to use them.

Key components:

• ttkbootstrap.Icon: The primary atom for icon usage.
• ttkbootstrap.style.icon_element: A per-state sugar utility for icon styling.

In version 2.0, ttkbootstrap is undergoing API normalization for several core widgets (Window, Toplevel, dialogs, and Tableview). To prevent breaking existing code, the project uses a Hybrid posture:

• High-value surfaces (Window, Toplevel, and dialogs) are being normalized with warn-and-normalize aliases via style/_compat.py. These aliases will provide warnings during 2.x and will be removed in 3.0.
• Tableview is receiving bug fixes, dead code removal, and re-exports, but established method names are being preserved for now to avoid massive documentation churn. A separate migration for method renaming is planned for a later release.

Use the feature guides for deep dives into specific subsystems:

• Typography: Managing Fonts and global families via set_global_family.
• Localization: Implementing live language switching using L(), LocaleVar, and set_locale.
• Input Validation: Using add_*_validation helpers and the @validator decorator.
• Icons: Using theme-aware Bootstrap Icons via the icon= keyword, apply_icon, or the Icon class.
• Windows & Menus: Setting up App/Toplevel windows and creating complex menu bars/submenus.
• Dialogs: Using Messagebox, Querybox, date/font/color pickers, and filedialog.
• Theming: Choosing themes, switching between light/dark modes, and accessing theme colors via style.colors.

Geometry managers determine how a widget is sized and positioned within its parent container. A widget will only be drawn once a geometry manager has placed it.

Crucial Rule: A single container should use only one geometry manager for its direct children (either pack or grid, but not both).

Users of version 2.0 will notice several visual updates that do not require code changes:

• Scrollbars: The default variant is now a flat square thumb, while round is a pill shape. Both feature a visible trough and an inset thumb with a minimum length to prevent them from disappearing in long lists.
• Buttons: Solid buttons now feature a subtle 1px hairline border derived from the button's fill color to ensure they are visible against similar backgrounds.
• Toolbuttons & Switches: The 'OFF' state for Toolbuttons and Switches is now more visually quiet, using a muted surface raise and de-emphasized text to ensure the 'ON' (selected) state carries the primary emphasis.

ttkbootstrap is a styling extension for vanilla tkinter, not a replacement widget library.

Key architectural principles:

• Uses standard tkinter widgets: It themes existing widgets rather than providing new ones. All standard tkinter concepts (geometry managers, variables, events, widget tree) apply directly.
• On-demand styling: Styles and themes are built only when used to minimize memory footprint.
• Lightweight dependencies: The project only requires Pillow.
• Performance: In version 2.0, assets are rendered once and shared, and theme switching is optimized to repaint only widgets currently on screen.