Skip to main content
This guide demonstrates common patterns used in CustomTkinter applications, drawn from real-world examples.

​
Grid Layout Configuration

Properly configuring grid layouts is essential for responsive UIs. Use grid_columnconfigure() and grid_rowconfigure() with weight parameters to control widget expansion. 
import customtkinter

class App(customtkinter.CTk):
    def __init__(self):
        super().__init__()
        
        # Configure grid layout (4x4)
        self.grid_columnconfigure(1, weight=1)
        self.grid_columnconfigure((2, 3), weight=0)
        self.grid_rowconfigure((0, 1, 2), weight=1)
Setting weight=1 allows columns/rows to expand and fill available space. Use weight=0 for fixed-size columns/rows.
A common pattern is creating a fixed sidebar with navigation buttons and settings controls. 
# Create sidebar frame with widgets
self.sidebar_frame = customtkinter.CTkFrame(self, width=140, corner_radius=0)
self.sidebar_frame.grid(row=0, column=0, rowspan=4, sticky="nsew")
self.sidebar_frame.grid_rowconfigure(4, weight=1)

# Add logo/title
self.logo_label = customtkinter.CTkLabel(
    self.sidebar_frame, 
    text="CustomTkinter", 
    font=customtkinter.CTkFont(size=20, weight="bold")
)
self.logo_label.grid(row=0, column=0, padx=20, pady=(20, 10))

# Add navigation buttons
self.sidebar_button_1 = customtkinter.CTkButton(
    self.sidebar_frame, 
    command=self.sidebar_button_event
)
self.sidebar_button_1.grid(row=1, column=0, padx=20, pady=10)

​
Appearance Mode Switching

Allow users to switch between light, dark, and system appearance modes.
1

Add OptionMenu for appearance mode

self.appearance_mode_optionemenu = customtkinter.CTkOptionMenu(
    self.sidebar_frame, 
    values=["Light", "Dark", "System"],
    command=self.change_appearance_mode_event
)
self.appearance_mode_optionemenu.grid(row=6, column=0, padx=20, pady=(10, 10))
2

Implement the callback function

def change_appearance_mode_event(self, new_appearance_mode: str):
    customtkinter.set_appearance_mode(new_appearance_mode)
3

Set initial mode at startup

# At module level or in __init__
customtkinter.set_appearance_mode("System")
customtkinter.set_default_color_theme("blue")

​
UI Scaling Pattern

Implement dynamic UI scaling to support different screen sizes and user preferences. 
def change_scaling_event(self, new_scaling: str):
    new_scaling_float = int(new_scaling.replace("%", "")) / 100
    customtkinter.set_widget_scaling(new_scaling_float)

# Add scaling option menu
self.scaling_optionemenu = customtkinter.CTkOptionMenu(
    self.sidebar_frame, 
    values=["80%", "90%", "100%", "110%", "120%"],
    command=self.change_scaling_event
)
self.scaling_optionemenu.set("100%")

​
Linking Widgets Together

Connect sliders to progress bars for synchronized updates. 
# Create slider and progressbar
self.progressbar_2 = customtkinter.CTkProgressBar(self.slider_progressbar_frame)
self.progressbar_2.grid(row=2, column=0, padx=(20, 10), pady=(10, 10), sticky="ew")

self.slider_1 = customtkinter.CTkSlider(
    self.slider_progressbar_frame, 
    from_=0, 
    to=1, 
    number_of_steps=4
)
self.slider_1.grid(row=3, column=0, padx=(20, 10), pady=(10, 10), sticky="ew")

# Link slider to progressbar
self.slider_1.configure(command=self.progressbar_2.set)
You can pass widget methods directly as command callbacks for simple data binding.

​
Indeterminate Progress Bar

Show continuous activity with an indeterminate progress bar. 
self.progressbar_1 = customtkinter.CTkProgressBar(self.container_frame)
self.progressbar_1.grid(row=1, column=0, padx=(20, 10), pady=(10, 10), sticky="ew")
self.progressbar_1.configure(mode="indeterminnate")
self.progressbar_1.start()

# Stop when task completes
# self.progressbar_1.stop()

​
Radio Button Groups

Create mutually exclusive option groups using radio buttons. 
import tkinter

# Create variable to track selection
self.radio_var = tkinter.IntVar(value=0)

# Create radio buttons sharing the same variable
self.radio_button_1 = customtkinter.CTkRadioButton(
    master=self.radiobutton_frame, 
    variable=self.radio_var, 
    value=0
)
self.radio_button_1.grid(row=1, column=2, pady=10, padx=20, sticky="n")

self.radio_button_2 = customtkinter.CTkRadioButton(
    master=self.radiobutton_frame, 
    variable=self.radio_var, 
    value=1
)
self.radio_button_2.grid(row=2, column=2, pady=10, padx=20, sticky="n")

self.radio_button_3 = customtkinter.CTkRadioButton(
    master=self.radiobutton_frame, 
    variable=self.radio_var, 
    value=2
)
self.radio_button_3.grid(row=3, column=2, pady=10, padx=20, sticky="n")
All radio buttons in a group must share the same variable and have unique values.

​
Input Dialogs

Collect user input with modal dialogs. 
def open_input_dialog_event(self):
    dialog = customtkinter.CTkInputDialog(
        text="Type in a number:", 
        title="CTkInputDialog"
    )
    result = dialog.get_input()
    print("CTkInputDialog:", result)

# Trigger from button
self.string_input_button = customtkinter.CTkButton(
    self.tabview.tab("CTkTabview"), 
    text="Open CTkInputDialog",
    command=self.open_input_dialog_event
)

​
Setting Default Widget States

Configure initial states for widgets after creation. 
# Disable widgets
self.sidebar_button_3.configure(state="disabled", text="Disabled CTkButton")
self.checkbox_3.configure(state="disabled")
self.radio_button_3.configure(state="disabled")

# Pre-select checkboxes
self.checkbox_1.select()

# Set default values for dropdowns
self.appearance_mode_optionemenu.set("Dark")
self.scaling_optionemenu.set("100%")
self.optionmenu_1.set("CTkOptionmenu")
self.combobox_1.set("CTkComboBox")

​
TabView Organization

Organize complex UIs with tabbed interfaces. 
# Create tabview
self.tabview = customtkinter.CTkTabview(self, width=250)
self.tabview.grid(row=0, column=2, padx=(20, 0), pady=(20, 0), sticky="nsew")

# Add tabs
self.tabview.add("CTkTabview")
self.tabview.add("Tab 2")
self.tabview.add("Tab 3")

# Configure grid for individual tabs
self.tabview.tab("CTkTabview").grid_columnconfigure(0, weight=1)
self.tabview.tab("Tab 2").grid_columnconfigure(0, weight=1)

# Add widgets to specific tabs
self.optionmenu_1 = customtkinter.CTkOptionMenu(
    self.tabview.tab("CTkTabview"), 
    dynamic_resizing=False,
    values=["Value 1", "Value 2", "Value Long Long Long"]
)
self.optionmenu_1.grid(row=0, column=0, padx=20, pady=(20, 10))

​
Working with Textboxes

Populate textboxes with initial content. 
self.textbox = customtkinter.CTkTextbox(self, width=250)
self.textbox.grid(row=0, column=1, padx=(20, 0), pady=(20, 0), sticky="nsew")

# Insert text at position "0.0" (line.column)
self.textbox.insert("0.0", "CTkTextbox\n\n" + 
    "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, " +
    "sed diam nonumy eirmod tempor invidunt ut labore et dolore " +
    "magna aliquyam erat, sed diam voluptua.\n\n" * 20
)

​
Segmented Buttons

Create button groups where only one can be selected at a time. 
self.seg_button_1 = customtkinter.CTkSegmentedButton(self.container_frame)
self.seg_button_1.grid(row=0, column=0, padx=(20, 10), pady=(10, 10), sticky="ew")

# Configure values and set default
self.seg_button_1.configure(values=["CTkSegmentedButton", "Value 2", "Value 3"])
self.seg_button_1.set("Value 2")

​
Transparent Buttons

Create buttons with transparent backgrounds and custom borders. 
self.main_button_1 = customtkinter.CTkButton(
    master=self, 
    fg_color="transparent", 
    border_width=2, 
    text_color=("gray10", "#DCE4EE")  # (light_mode_color, dark_mode_color)
)
self.main_button_1.grid(row=3, column=3, padx=(20, 20), pady=(20, 20), sticky="nsew")
Use fg_color="transparent" to create outline-style buttons. The border color automatically adapts to the theme.

Build docs developers (and LLMs) love

Get started for freeTalk to us