Checkbutton#

Checkbutton is the native ttk labeled on/off toggle (ttk.Checkbutton), themed by ttkbootstrap. This page is the complete reference for its options, methods, and styling.

Options#

Each option can be set in the constructor and changed later with configure().

Option

Type

Description

bootstyle

str

Constructor keyword. An accent color, optionally with a variant. See Styling options for the available styles.

icon

str

Constructor keyword. A Bootstrap Icons glyph name (e.g. "gear-fill") shown on the widget; theme-aware — it follows the foreground color and states. See the Icons guide.

icon_size

int

Constructor keyword. The glyph size in pixels (scaled for high-DPI).

icon_only

bool

Constructor keyword. Show only the glyph (hide the text) and pad the widget into a square. Default False.

text

str

The label shown beside the check.

textvariable

Variable

A StringVar whose value is shown as the label and tracked live.

variable

Variable

The variable that holds the check state.

onvalue

any

The value written to variable when checked.

offvalue

any

The value written to variable when unchecked.

command

callable

The function called when the checkbutton is invoked — clicked, or activated with Space.

image

PhotoImage

An image to display in place of, or beside, the text.

compound

str

How text and image are combined: "none", "left", "right", "top", "bottom", or "center".

underline

int

The character index to underline (for a keyboard mnemonic), or -1.

width

int

The requested width in characters (negative sets a minimum).

padding

int | tuple

Extra space around the label, in pixels (a single value, or per-side).

state

str

"normal" or "disabled". For finer control use the state method (see Capabilities).

cursor

str

The mouse cursor over the checkbutton (see Cursors).

takefocus

bool

Whether the checkbutton accepts keyboard focus during traversal.

Methods#

invoke()

Toggle the check state and run its command.

Returns:

the command’s return value.

Styling options#

This section is for changing how the checkbutton looks. Define a style with style.configure(...) (and style.map(...) for per-state colors), then apply it with Checkbutton(style=...).

Bootstyle mapping#

Any of the accent colors – primary, secondary, success, info, warning, danger, light, dark – substitutes for primary below. neutral does not apply to this family.

bootstyle

ttk style name

primary

primary.TCheckbutton

Layout (elements)#

The widget is drawn from these nested parts. Each is an element you can target by name in a custom layout:

Checkbutton.padding
  primary.TCheckbutton.indicator
  primary.TCheckbutton.spacer
  Checkbutton.focus
    Checkbutton.label

Configurable style options#

Note

The check indicator is drawn from a pre-rendered image keyed to the bootstyle color; style.configure(...) does not reach it. The options listed here style only the widget’s non-image parts (such as the focus ring and text label). To recolor the check indicator, choose a bootstyle color; to change its shape or artwork, build a custom image-based layout – see Custom styles.

Options you can set with style.configure(...) / style.map(...):

anchor, background, compound, embossed, focuscolor, focussolid, focusthickness, font, foreground, image, justify, padding, relief, shiftrelief, space, stipple, text, underline, width, wraplength

Supported states#

The states you can target with style.map(...) to vary appearance by interaction:

disabled

Hand-styling example#

import ttkbootstrap as ttk

app = ttk.App()
style = app.style

style.configure("my.TCheckbutton", background="#3498db", foreground="white")
ttk.Checkbutton(app, text="Custom", style="my.TCheckbutton").pack(padx=8, pady=8)

app.mainloop()

Switch (toggle) variant#

Rendered as a switch, a checkbutton uses these Toggle style names instead:

Bootstyle mapping#

Any of the accent colors – primary, secondary, success, info, warning, danger, light, dark – substitutes for primary below. neutral does not apply to this family.

bootstyle

ttk style name

primary toggle

primary.Toggle

primary round toggle

primary.Round.Toggle

primary square toggle

primary.Square.Toggle

Layout (elements)#

The widget is drawn from these nested parts. Each is an element you can target by name in a custom layout:

Toolbutton.border
  Toolbutton.padding
    primary.Toggle.indicator
    primary.Toggle.spacer
    Toolbutton.focus
      Toolbutton.label

Configurable style options#

Note

The toggle is drawn from a pre-rendered image keyed to the bootstyle color; style.configure(...) does not reach it. The options listed here style only the widget’s non-image parts (such as the focus ring and text label). To recolor the toggle, choose a bootstyle color; to change its shape or artwork, build a custom image-based layout – see Custom styles.

Options you can set with style.configure(...) / style.map(...):

anchor, background, bordercolor, borderwidth, compound, darkcolor, embossed, focuscolor, focussolid, focusthickness, font, foreground, image, justify, lightcolor, padding, relief, shiftrelief, space, stipple, text, underline, width, wraplength

Supported states#

The states you can target with style.map(...) to vary appearance by interaction:

disabled, selected

Hand-styling example#

import ttkbootstrap as ttk

app = ttk.App()
style = app.style

style.configure("my.Toggle", background="#3498db", foreground="white")
ttk.Checkbutton(app, text="Custom", style="my.Toggle").pack(padx=8, pady=8)

app.mainloop()

Shared capabilities#

Checkbutton also has the methods every widget inherits — configuration, placement, event binding, lifecycle, focus, and introspection — plus the ttk state methods state / instate / identify. These are documented under Capabilities.

See also#