DOCUMENTATION.md

CTkSidebar Documentation

1 Installation

Get the latest version from PyPI:

pip install ctk-sidebar

The only direct dependencies are pillow, and, of course, CustomTkinter itself.

2 Component Instantiation

Depending on your requirements, you can either instantiate the CTkSidebarNavigation or the CTkSidebar component. As the names imply, the navigation component handles automatic view switching, while the sidebar allows more custom functionality, and only creates the sidebar.

2.1 Navigation Component

The navigation component is meant to be used as the toplevel component in your Tk window. It contains a sidebar and containers to display the different views you assign to each menu item.

Example:

import customtkinter as CTk
from ctksidebar import CTkSidebarNavigation

app = CTk.CTk()
app.geometry("640x480")

nav = CTkSidebarNavigation(master=app)
nav.pack(fill="both", expand=True)

side = nav.sidebar

Using the API calls described below, you can now populate the side bar and view containers.

2.2 Sidebar Component

The sidebar can also be used as a standalone component. In this case, you have to handle (custom) navigation yourself by listening to the commands of each menu item.

Setting up a sidebar on the left side of a parent component can be done as follows:

sidebar = CTkSidebar(master=parent)
sidebar.pack(side="left", fill="y")

3 Sidebar API

CTkSidebarNavigation

The toplevel component to be instantiated on your window when needing a side bar with automatic navigation.

Constructor

Parameter	Type	Default	Description
master	Any	-	The parent Tk component. Required.
width	int	220	The width of the sidebar.
theme	CTkSidebarTheme | None	None	When provided, allows to set a custom theme. See dedicated section on styling.
indent_level	int	0	Sets a custom indentation level for the items in the current menu. Submenus automatically use the next indentation level.
single_expanded_submenu	bool	False	When True, only one submenu per indentation level can be expanded at a time. Other submenus automatically collapse.

Properties

.sidebar

Type: CTkSidebar

A reference to the actual side bar embedded in the navigation container. A side bar is automatically instantiated when calling the CTkSidebarNavigation constructor. This property must be used to populate the side bar with menu items, see description of the CTkSidebar class.

Methods

.view(id)

Returns the frame for the view with the passed ID. The ID must match one of the previously added items using .sidebar..add_item(...). Use the return value as the parent when populating the view of each sidebar item.

Return value: CTk.CTkFrame

Parameter	Type	Default	Description
id	int | str	-	One of the IDs previously passed when adding a menu item. Required.

Example:

nav = CTkSidebarNavigation(master=app)
nav.sidebar.add_item(id="home", text="Home")
nav.sidebar.add_item(id="orders", text="Orders")
home_frame = nav.view("home")
home_title = CTk.CTkLabel(master=home_frame, text="Home")

.set(id)

Switches the view and selected side bar item to the item with given ID. After populating the side bar, a call to this method is needed to set the initially selected item and view. Can also be used to programmatically switch to another view.

Return value: None

Parameter	Type	Default	Description
id	int | str	-	One of the IDs previously passed when adding a menu item. Required.

Example:

nav = CTkSidebarNavigation()
nav.sidebar.add_item(id="home", text="Home")
nav.sidebar.add_item(id="orders", text="Orders")
nav.set("home")

CTkSidebar

Constructor

Parameter	Type	Default	Description
master	Any	-	The parent Tk component. Required.
width	int	220	The width of the side bar.
theme	CTkSidebarTheme | None	None	When provided, allows to set a custom theme. See dedicated section on styling.
indent_level	int	0	Sets a custom indentation level for the items in the current menu. Submenus automatically use the next indentation level.
single_expanded_submenu	bool	False	When True, only one submenu per indentation level can be expanded at a time. Other submenus automatically collapse.

Methods

.add_item(id, text, command, icon, icon_size, override_text_x, override_icon_x)

Return type: None

Adds a new menu item to the side bar.

As an icon you can either pass a PIL Image.Image or a CTk.CTkImage. When a PIL Image.Image is passed, the image automatically gets colorized to match the menu item text. If this behavior is not desired, you can pass your own tuple of CTk.CTkImages to specify an image for the deselected and selected menu item state.

Parameter	Type	Default	Description
id	int | str	None	A unique ID for this menu item. Required when using the navigation component.
text	str	""	Text label that appears in the side bar.
command	Callable[[int|str], None] | None	None	A custom callback when this menu item is clicked. The `id` is passed as a parameter.
icon	Image.Image | tuple[CTk.CTkImage, CTk.CTkImage] | None	None	An optional icon for this menu item. Pass a PIL image if you want automatic colorization, or two CTk.CTkImages to provide icons for the deselected and selected state of the item.
icon_size	tuple[int, int]	(20, 20)	The size of the icon.
override_text_x	int | None	None	Specify a custom X position for the label text on this item, overriding the theme's default.
override_icon_x	int | None	None	Specify a custom X position for the label icon on this item, overriding the theme's default.

Example:

import customtkinter as CTk
from PIL import Image
from ctksidebar import CTkSidebar

# <init your app here>

side = CTkSidebar(master=app)

# Automatically colorized icons
side.add_item(id="home", text="Dashboard", icon=Image.open("home.png"))

# Custom icon for deselected and selected state, no colorization
order_icon = (
    CTk.CTkImage(Image.open("order.png")),
    CTk.CTkImage(Image.open("order_selected.png")),
)
side.add_item(id="order_icon", text="Dashboard", icon=order_icon)

.add_submenu(id, text, command, icon, icon_size, override_text_x, override_icon_x, indent_level, theme, expanded)

Adds a menu item that has a submenu. Works similarly as .add_item(), except that it returns a new CTkSidebar object that allows you to populate the submenu.

Return type: CTkSidebar

Parameter	Type	Default	Description
id	int | str	None	A unique ID for this menu item. Required when using the navigation component.
text	str	""	Text label that appears in the side bar.
command	Callable[[int|str], None] | None	None	A custom callback when this menu item is clicked. The `id` is passed as a parameter.
icon	Image.Image | tuple[CTk.CTkImage, CTk.CTkImage] | None	None	An optional icon for this menu item. Pass a PIL image if you want automatic colorization, or two CTk.CTkImages to provide icons for the deselected and selected state of the item.
icon_size	tuple[int, int]	(20, 20)	The size of the icon.
override_text_x	int | None	None	Specify a custom X position for the label text on this item, overriding the theme's default.
override_icon_x	int | None	None	Specify a custom X position for the label icon on this item, overriding the theme's default.
indent_level	int | None	None	Specify a custom indentation level for the submenu. When None, the level is automatically incremented relatively to the parent menu.
theme	CTkSidebarTheme | None	None	Specify a custom theme for the submenu. By default, all submenus get the 'secondary' theme. Also see the description of `CTkSidebarTheme`.
expanded	bool	True	Whether the submenu is initially expanded.

Example:

# - Home
# - Orders
#   - List
#   - Reports
sidebar.add_item(id="Home", text="Home")
order_submenu = side.add_submenu(id="orders", text="Orders")
order_submenu.add_item(id="order-list", text="List")
order_submenu.add_item(id="order-reports", text="Reports")

.add_frame(frame, pady)

Adds a custom frame or widget in the side bar. Useful for adding a header or custom separators.

Important

The master of the widget to add must be the CTkSidebar on which this call is made. The CTkSidebar automatically integrates it in its layout, so no calls to .pack(), .place() or .grid() are needed.

Return type: None

Parameter	Type	Default	Description
frame	CTk.CTkBaseClass	-	The customTkinter widget to add. Required.
pady	int | tuple[int,int] | None	None	Optional vertical padding to add when inserting it in the side bar.

.add_separator(width, height, line_color, line_thickness, rounded_line_end)

Adds a separator line to the side bar.

Parameter	Type	Default	Description
width	int | None	None	The width of the (centered) separation line. When `None`, the default from the theme is used.
height	int | None	None	The total height of the separator. When `None`, the default from the theme is used.
line_color	str | tuple[str, str] | None	None	The color of the separation line. Can be a single color string, are a tuple for specifying different light/dark colors. When `None`, the default from the theme is used.
line_color	bool	None	The type of line caps used for drawing the seperation line. Set True for rounded end caps, False for butt caps. When `None`, the default from the theme is used.

.add_spacing(height)

Adds empty vertical space to the side bar.

Parameter	Type	Default	Description
height	int | None	None	The height of the empty space to add.

4 Styling

The default styling can be overridden by passing a CTkSidebarTheme object to the constructor of CTkSidebarNavigation and CTkSidebar. When creating a submenu using CTkSidebar.add_submenu(), a custom theme can be passed to override the style of the submenu.

CTkSidebarTheme

Constructor

Parameter	Type	Default	Description
load_default	Literal['primary', 'secondary']	'primary'	Loads the default styles for all non-specified parameters. The primary default normally styles non-submenu items, whereas the secondary style is for submenus.
bg_color	Optional[str]	None	Background color of the sidebar.
padx	Optional[int]	None	Horizontal padding inside the sidebar frame.
pady	Optional[int|tuple[int,int]]	None	Vertical padding inside the sidebar frame.
submenu_pady	Optional[int|tuple[int,int]]	None	Vertical padding before and after submenu sections. If desired, you can specify a tuple for (top, bottom) padding.
button_color	Optional[str|list[str]]	None	Background color of unselected sidebar buttons.
button_color_hover	Optional[str|list[str]]	None	Background color when hovering over buttons.
button_color_selected	Optional[str|list[str]]	None	Background color of the selected button.
button_corner_radius	Optional[int]	None	Corner radius of sidebar buttons.
button_height	Optional[int]	None	Height of sidebar buttons.
text_color	Optional[str|list[str]]	None	Text color of unselected sidebar buttons.
text_color_hover	Optional[str|list[str]]	None	Text color when hovering over buttons.
text_color_selected	Optional[str|list[str]]	None	Text color of the selected button.
label_indent	Optional[int]	None	Base indentation for sidebar item labels.
label_indent_increment	Optional[int]	None	Additional indentation per submenu level.
label_align_ref	Optional[Literal['text', 'icon']]	None	Horizontally align labels of menu items by their text or icon left position.
icon_text_margin	Optional[int]	None	Horizontal margin between icon and text in sidebar items.
separator_line_color	Optional[str|list[str]]	None	Color of separator lines.
separator_line_thickness	Optional[int]	None	Thickness of separator lines.
separator_height	Optional[int]	None	Total height of a separator item.
separator_width	Optional[int]	None	Width of the (centered) separator line.
separator_rounded_line_end	Optional[bool]	None	Whether separator lines have rounded or 'butt' ends.
submenu_marker_thickness	Optional[str|list[str]]	None	Thickness of the submenu expansion marker line.
submenu_marker_padx	Optional[int]	None	Horizontal offset of the submenu marker line with respect to the button's left edge.
submenu_marker_pady	Optional[int]	None	Vertical padding of the submenu marker line with respect to the button's top and bottom edges.