Documentation Index
Fetch the complete documentation index at: https://mintlify.com/TomSchimansky/CustomTkinter/llms.txt
Use this file to discover all available pages before exploring further.
CTkFrame
Frame with rounded corners and border. Default foreground colors are set according to theme. To make the frame transparent set fg_color=None.
Constructor
CTkFrame(
master: Any,
width: int = 200,
height: int = 200,
corner_radius: Optional[Union[int, str]] = None,
border_width: Optional[Union[int, str]] = None,
bg_color: Union[str, Tuple[str, str]] = "transparent",
fg_color: Optional[Union[str, Tuple[str, str]]] = None,
border_color: Optional[Union[str, Tuple[str, str]]] = None,
background_corner_colors: Union[Tuple[Union[str, Tuple[str, str]]], None] = None,
overwrite_preferred_drawing_method: Union[str, None] = None,
**kwargs
)
Parameters
The parent widget where the frame will be placed.
Width of the frame in pixels.
Height of the frame in pixels.
corner_radius
Optional[Union[int, str]]
default:"None"
Radius of the rounded corners. If None, uses theme default.
border_width
Optional[Union[int, str]]
default:"None"
Width of the frame border. If None, uses theme default.
Color Parameters
bg_color
Union[str, Tuple[str, str]]
default:"'transparent'"
Background color behind the frame. 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 frame (main frame color). If None, uses theme default with automatic color adjustment for nested frames. Set to None for a transparent frame.Automatic nesting behavior: When a CTkFrame is placed inside another CTkFrame, the inner frame automatically uses a slightly different shade (“top_fg_color”) to create visual distinction.
border_color
Optional[Union[str, Tuple[str, str]]]
default:"None"
Color of the frame border. If None, uses theme default.
Advanced 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.
overwrite_preferred_drawing_method
Union[str, None]
default:"None"
Override the default drawing method used by the DrawEngine. Advanced option for specific rendering requirements.
Methods
Update frame attributes after creation.
frame.configure(
fg_color="lightblue",
border_color="darkblue",
border_width=2,
corner_radius=15
)
- All constructor parameters
require_redraw (bool): Force a redraw of the widget
Important: When changing fg_color, all child CTkBaseClass widgets automatically update their bg_color to match the new frame color. Similarly, when bg_color changes and fg_color is “transparent”, child widgets update accordingly.
cget()
Get the current value of a frame attribute.
value = frame.cget("fg_color")
attribute_name (str): Name of the attribute to retrieve
Returns: The current value of the specified attribute
Available attributes:
corner_radius, border_widthfg_color, border_color, background_corner_colors
winfo_children()
Get a list of all child widgets in the frame.
children = frame.winfo_children()
bind()
Bind an event to the frame.
frame.bind("<Button-1>", click_handler, add=True)
sequence (str): Event sequence (e.g., "<Button-1>", "<Enter>")command (Callable): Function to call when event occursadd (bool): Must be True or ”+” to preserve internal callbacks
unbind()
Remove an event binding from the frame.
frame.unbind("<Button-1>")
sequence (str): Event sequence to unbindfuncid (str): Must be None (parameter included for compatibility)
Usage Examples
Basic Frame
import customtkinter as ctk
root = ctk.CTk()
frame = ctk.CTkFrame(root)
frame.pack(pady=20, padx=20, fill="both", expand=True)
# Add widgets to the frame
label = ctk.CTkLabel(frame, text="Inside Frame")
label.pack(pady=10)
root.mainloop()
Frame with Custom Styling
frame = ctk.CTkFrame(
root,
width=300,
height=200,
fg_color="#2b2b2b",
border_color="#1f538d",
border_width=3,
corner_radius=15
)
frame.pack(pady=20, padx=20)
Nested Frames
# Outer frame
outer_frame = ctk.CTkFrame(
root,
width=400,
height=300
)
outer_frame.pack(pady=20, padx=20)
# Inner frame (automatically gets different shade)
inner_frame = ctk.CTkFrame(
outer_frame,
width=300,
height=200
)
inner_frame.pack(pady=20, padx=20)
Transparent Frame
frame = ctk.CTkFrame(
root,
fg_color="transparent",
border_width=0
)
frame.pack(pady=20, padx=20)
Frame with Grid Layout
frame = ctk.CTkFrame(root)
frame.pack(pady=20, padx=20)
# Configure grid
frame.grid_columnconfigure((0, 1), weight=1)
frame.grid_rowconfigure((0, 1), weight=1)
# Add widgets using grid
ctk.CTkButton(frame, text="Button 1").grid(row=0, column=0, pady=10, padx=10)
ctk.CTkButton(frame, text="Button 2").grid(row=0, column=1, pady=10, padx=10)
ctk.CTkButton(frame, text="Button 3").grid(row=1, column=0, pady=10, padx=10)
ctk.CTkButton(frame, text="Button 4").grid(row=1, column=1, pady=10, padx=10)
# Create main frame
main_frame = ctk.CTkFrame(root)
main_frame.pack(fill="both", expand=True, pady=10, padx=10)
# Add multiple widgets
for i in range(10):
widget_frame = ctk.CTkFrame(main_frame)
widget_frame.pack(pady=5, padx=5, fill="x")
label = ctk.CTkLabel(widget_frame, text=f"Item {i+1}")
label.pack(side="left", padx=10)
button = ctk.CTkButton(widget_frame, text="Action", width=80)
button.pack(side="right", padx=10)
# Sidebar frame
sidebar = ctk.CTkFrame(
root,
width=200,
corner_radius=0
)
sidebar.pack(side="left", fill="y")
# Sidebar title
title = ctk.CTkLabel(
sidebar,
text="Navigation",
font=("Arial", 16, "bold")
)
title.pack(pady=20, padx=20)
# Navigation buttons
for item in ["Home", "Settings", "Profile", "Logout"]:
btn = ctk.CTkButton(sidebar, text=item, width=160)
btn.pack(pady=5, padx=20)
Dynamic Color Update
frame = ctk.CTkFrame(root)
frame.pack(pady=20, padx=20)
# Add some child widgets
label = ctk.CTkLabel(frame, text="Child Label")
label.pack(pady=10)
button = ctk.CTkButton(frame, text="Child Button")
button.pack(pady=10)
# Change frame color - child widgets automatically update their bg_color
def change_color():
frame.configure(fg_color="#1f538d")
color_button = ctk.CTkButton(root, text="Change Frame Color", command=change_color)
color_button.pack(pady=10)