Skip to main content

​
CTkButton

Button with rounded corners, border, hover effect, image support, click command and textvariable.

​
Constructor

CTkButton(
    master: Any,
    width: int = 140,
    height: int = 28,
    corner_radius: Optional[int] = None,
    border_width: Optional[int] = None,
    border_spacing: int = 2,
    bg_color: Union[str, Tuple[str, str]] = "transparent",
    fg_color: Optional[Union[str, Tuple[str, str]]] = None,
    hover_color: Optional[Union[str, Tuple[str, str]]] = None,
    border_color: Optional[Union[str, Tuple[str, str]]] = None,
    text_color: Optional[Union[str, Tuple[str, str]]] = None,
    text_color_disabled: Optional[Union[str, Tuple[str, str]]] = None,
    background_corner_colors: Union[Tuple[Union[str, Tuple[str, str]]], None] = None,
    round_width_to_even_numbers: bool = True,
    round_height_to_even_numbers: bool = True,
    text: str = "CTkButton",
    font: Optional[Union[tuple, CTkFont]] = None,
    textvariable: Union[tkinter.Variable, None] = None,
    image: Union[CTkImage, ImageTk.PhotoImage, None] = None,
    state: str = "normal",
    hover: bool = True,
    command: Union[Callable[[], Any], None] = None,
    compound: str = "left",
    anchor: str = "center"
)

​
Parameters

​
master
Any
required
The parent widget where the button will be placed.
​
width
int
default:"140"
Width of the button in pixels.
​
height
int
default:"28"
Height of the button in pixels.
​
corner_radius
Optional[int]
default:"None"
Radius of the rounded corners. If None, uses theme default. The actual corner radius is limited to half of the current height.
​
border_width
Optional[int]
default:"None"
Width of the button border. If None, uses theme default.
​
border_spacing
int
default:"2"
Spacing between the border and the button content.

​
Color Parameters

​
bg_color
Union[str, Tuple[str, str]]
default:"'transparent'"
Background color behind the button. Can be a single color string or a tuple of (light_mode_color, dark_mode_color).
​
fg_color
Optional[Union[str, Tuple[str, str]]]
default:"None"
Foreground color of the button (main button color). If None, uses theme default. Set to “transparent” for a transparent button.
​
hover_color
Optional[Union[str, Tuple[str, str]]]
default:"None"
Color when the mouse hovers over the button. If None, uses theme default.
​
border_color
Optional[Union[str, Tuple[str, str]]]
default:"None"
Color of the button border. If None, uses theme default.
​
text_color
Optional[Union[str, Tuple[str, str]]]
default:"None"
Color of the button text. If None, uses theme default.
​
text_color_disabled
Optional[Union[str, Tuple[str, str]]]
default:"None"
Color of the text when the button is disabled. If None, uses theme default.

​
Rendering Options

​
background_corner_colors
Union[Tuple[Union[str, Tuple[str, str]]], None]
default:"None"
Tuple of 4 colors for drawing background corners: (top_left, top_right, bottom_right, bottom_left). Used for special rendering cases.
​
round_width_to_even_numbers
bool
default:"True"
Whether to round the widget width to even numbers for better rendering.
​
round_height_to_even_numbers
bool
default:"True"
Whether to round the widget height to even numbers for better rendering.

​
Text and Content Parameters

​
text
str
default:"'CTkButton'"
The text displayed on the button.
​
font
Optional[Union[tuple, CTkFont]]
default:"None"
Font for the button text. Can be a CTkFont object or a tuple like (“Arial”, 12). If None, uses default font.
​
textvariable
Union[tkinter.Variable, None]
default:"None"
Tkinter variable to bind to the button text for dynamic updates.
​
image
Union[CTkImage, ImageTk.PhotoImage, None]
default:"None"
Image to display on the button. Can be a CTkImage or PhotoImage object.
​
compound
str
default:"'left'"
Position of the image relative to text. Options: “left”, “right”, “top”, “bottom”.
​
anchor
str
default:"'center'"
Anchor position for the button content. Options: “center”, “n”, “s”, “e”, “w”, “ne”, “nw”, “se”, “sw”.

​
Behavior Parameters

​
state
str
default:"'normal'"
State of the button. Options: “normal” or “disabled”.
​
hover
bool
default:"True"
Whether to enable hover effects.
​
command
Union[Callable[[], Any], None]
default:"None"
Function to call when the button is clicked.

​
Methods

​
configure()

Update button attributes after creation. 
button.configure(
    corner_radius=10,
    border_width=2,
    fg_color="blue",
    text="Click Me",
    state="normal"
)
Configurable attributes:
  • All constructor parameters
  • require_redraw (bool): Force a redraw of the widget

​
cget()

Get the current value of a button attribute. 
value = button.cget("text")
Parameters:
  • attribute_name (str): Name of the attribute to retrieve
Returns: The current value of the specified attribute Available attributes:
  • corner_radius, border_width, border_spacing
  • fg_color, hover_color, border_color, text_color, text_color_disabled, background_corner_colors
  • text, font, textvariable, image, state, hover, command, compound, anchor

​
invoke()

Programmatically trigger the button’s command function. 
result = button.invoke()
Returns: The return value of the command function, or None if button is disabled or no command is set

​
bind()

Bind an event to the button. 
button.bind("<Button-3>", right_click_handler, add=True)
Parameters:
  • sequence (str): Event sequence (e.g., "<Button-1>", "<Enter>")
  • command (Callable): Function to call when event occurs
  • add (Union[str, bool]): Must be ”+” or True to preserve internal callbacks

​
unbind()

Remove an event binding from the button. 
button.unbind("<Button-3>")
Parameters:
  • sequence (str): Event sequence to unbind
  • funcid (str): Must be None (parameter included for compatibility)

​
focus(), focus_set(), focus_force()

Control keyboard focus on the button. 
button.focus()
button.focus_set()
button.focus_force()

​
Usage Examples

​
Basic Button

import customtkinter as ctk

root = ctk.CTk()

def button_clicked():
    print("Button clicked!")

button = ctk.CTkButton(
    root,
    text="Click Me",
    command=button_clicked
)
button.pack(pady=20)

root.mainloop()

​
Button with Custom Colors

button = ctk.CTkButton(
    root,
    text="Custom Button",
    fg_color="#1f538d",
    hover_color="#14375e",
    text_color="white",
    border_color="#14375e",
    border_width=2,
    corner_radius=10
)
button.pack(pady=10)

​
Button with Image

from PIL import Image

my_image = ctk.CTkImage(
    light_image=Image.open("icon_light.png"),
    dark_image=Image.open("icon_dark.png"),
    size=(20, 20)
)

button = ctk.CTkButton(
    root,
    text="Download",
    image=my_image,
    compound="left"
)
button.pack(pady=10)

​
Button with Dynamic Text

import tkinter as tk

text_var = tk.StringVar(value="Initial Text")

button = ctk.CTkButton(
    root,
    textvariable=text_var,
    command=lambda: text_var.set("Text Changed!")
)
button.pack(pady=10)

​
Disabled Button

button = ctk.CTkButton(
    root,
    text="Disabled Button",
    state="disabled",
    text_color_disabled="gray"
)
button.pack(pady=10)

​
Button with Different Anchor

button = ctk.CTkButton(
    root,
    text="Left Aligned",
    width=200,
    anchor="w"
)
button.pack(pady=10)

Build docs developers (and LLMs) love

Get started for freeTalk to us