Skip to main content
Scrollbar widget with rounded corners and configurable spacing. Connects to scrollable widgets through the .set() method and the command parameter.

​
Constructor

CTkScrollbar(master, width, height, corner_radius, border_spacing,
             minimum_pixel_length, bg_color, fg_color, button_color,
             button_hover_color, hover, command, orientation)
​
master
widget
required
Parent widget
​
width
int
default:"16 (vertical) / 200 (horizontal)"
Width of the scrollbar in pixels
​
height
int
default:"200 (vertical) / 16 (horizontal)"
Height of the scrollbar in pixels
​
corner_radius
int
default:"theme"
Corner radius in pixels
​
border_spacing
int
default:"theme"
Spacing between scrollbar button and border
​
minimum_pixel_length
int
default:"20"
Minimum pixel length of the scrollbar button
​
bg_color
str | tuple[str, str]
default:"transparent"
Background color
​
fg_color
str | tuple[str, str]
default:"theme"
Foreground color of the scrollbar track
​
button_color
str | tuple[str, str]
default:"theme"
Color of the scrollbar button
​
button_hover_color
str | tuple[str, str]
default:"theme"
Hover color of the scrollbar button
​
hover
bool
default:"True"
Enable hover effect on the scrollbar button
​
command
callable
default:"None"
Callback function for scrolling commands. Typically set to the scrollable widget’s .xview or .yview method
​
orientation
str
default:"vertical"
Orientation of the scrollbar: “vertical” or “horizontal”

​
Methods

​
set

.set(start_value, end_value)
Update the scrollbar position. Typically called by the scrollable widget’s scroll command.
​
start_value
float
required
Starting position of the scrollbar button (0.0 to 1.0)
​
end_value
float
required
Ending position of the scrollbar button (0.0 to 1.0)

​
get

.get() -> tuple[float, float]
Get the current scrollbar position as a tuple of (start_value, end_value).

​
configure

.configure(**kwargs)
Configure widget parameters. Accepts all constructor parameters.

​
cget

.cget(attribute_name) -> any
Get the value of a widget attribute.

​
Usage Examples

​
Basic Vertical Scrollbar with Canvas

import customtkinter as ctk
import tkinter

app = ctk.CTk()

# Create a canvas
canvas = tkinter.Canvas(app, width=300, height=400)
canvas.pack(side="left", fill="both", expand=True)

# Create vertical scrollbar
scrollbar = ctk.CTkScrollbar(
    app,
    orientation="vertical",
    command=canvas.yview
)
scrollbar.pack(side="right", fill="y")

# Connect canvas to scrollbar
canvas.configure(yscrollcommand=scrollbar.set)

# Add content to canvas
for i in range(50):
    canvas.create_text(150, i * 30, text=f"Item {i+1}")

canvas.configure(scrollregion=canvas.bbox("all"))

app.mainloop()

​
Horizontal Scrollbar

import customtkinter as ctk
import tkinter

app = ctk.CTk()

frame = ctk.CTkFrame(app)
frame.pack(fill="both", expand=True)

canvas = tkinter.Canvas(frame, width=400, height=200)
canvas.pack(side="top", fill="both", expand=True)

# Create horizontal scrollbar
scrollbar = ctk.CTkScrollbar(
    frame,
    orientation="horizontal",
    command=canvas.xview
)
scrollbar.pack(side="bottom", fill="x")

canvas.configure(xscrollcommand=scrollbar.set)

# Add wide content
for i in range(20):
    canvas.create_text(i * 100, 100, text=f"Column {i+1}")

canvas.configure(scrollregion=canvas.bbox("all"))

app.mainloop()

​
Custom Colors

import customtkinter as ctk
import tkinter

app = ctk.CTk()

canvas = tkinter.Canvas(app, width=300, height=400)
canvas.pack(side="left", fill="both", expand=True)

scrollbar = ctk.CTkScrollbar(
    app,
    orientation="vertical",
    command=canvas.yview,
    fg_color="#2b2b2b",
    button_color="#0066cc",
    button_hover_color="#0052a3"
)
scrollbar.pack(side="right", fill="y")

canvas.configure(yscrollcommand=scrollbar.set)

for i in range(50):
    canvas.create_text(150, i * 30, text=f"Item {i+1}")

canvas.configure(scrollregion=canvas.bbox("all"))

app.mainloop()

​
Both Scrollbars (Vertical and Horizontal)

import customtkinter as ctk
import tkinter

app = ctk.CTk()

frame = ctk.CTkFrame(app)
frame.pack(fill="both", expand=True, padx=10, pady=10)

canvas = tkinter.Canvas(frame, width=400, height=300, bg="#2b2b2b")
canvas.grid(row=0, column=0, sticky="nsew")

# Vertical scrollbar
v_scrollbar = ctk.CTkScrollbar(
    frame,
    orientation="vertical",
    command=canvas.yview
)
v_scrollbar.grid(row=0, column=1, sticky="ns")

# Horizontal scrollbar
h_scrollbar = ctk.CTkScrollbar(
    frame,
    orientation="horizontal",
    command=canvas.xview
)
h_scrollbar.grid(row=1, column=0, sticky="ew")

canvas.configure(
    yscrollcommand=v_scrollbar.set,
    xscrollcommand=h_scrollbar.set
)

frame.grid_rowconfigure(0, weight=1)
frame.grid_columnconfigure(0, weight=1)

# Add content that requires both scrollbars
for i in range(30):
    for j in range(30):
        canvas.create_text(j * 100, i * 50, text=f"({i},{j})")

canvas.configure(scrollregion=canvas.bbox("all"))

app.mainloop()

​
Disable Hover Effect

import customtkinter as ctk
import tkinter

app = ctk.CTk()

canvas = tkinter.Canvas(app, width=300, height=400)
canvas.pack(side="left", fill="both", expand=True)

scrollbar = ctk.CTkScrollbar(
    app,
    orientation="vertical",
    command=canvas.yview,
    hover=False  # Disable hover effect
)
scrollbar.pack(side="right", fill="y")

canvas.configure(yscrollcommand=scrollbar.set)

for i in range(50):
    canvas.create_text(150, i * 30, text=f"Item {i+1}")

canvas.configure(scrollregion=canvas.bbox("all"))

app.mainloop()

​
Connection Pattern

To properly connect a scrollbar to a scrollable widget:
  1. Set the scrollbar’s command parameter to the widget’s view method (.xview or .yview)
  2. Set the widget’s scroll command to the scrollbar’s .set() method
# For vertical scrolling:
scrollbar = CTkScrollbar(parent, command=widget.yview)
widget.configure(yscrollcommand=scrollbar.set)

# For horizontal scrolling:
scrollbar = CTkScrollbar(parent, orientation="horizontal", command=widget.xview)
widget.configure(xscrollcommand=scrollbar.set)

Build docs developers (and LLMs) love

Get started for freeTalk to us