A simple scrollable frame class for tkinter, including example usage.

tk_scroll_demo.py

# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at https://mozilla.org/MPL/2.0/.

import tkinter as tk
import platform

# ************************
# Scrollable Frame Class
# ************************
class ScrollFrame(tk.Frame):
    def __init__(self, parent):
        super().__init__(parent) # create a frame (self)

        self.canvas = tk.Canvas(self, borderwidth=0, background="#ffffff")          #place canvas on self
        self.viewPort = tk.Frame(self.canvas, background="#ffffff")                    #place a frame on the canvas, this frame will hold the child widgets 
        self.vsb = tk.Scrollbar(self, orient="vertical", command=self.canvas.yview) #place a scrollbar on self 
        self.canvas.configure(yscrollcommand=self.vsb.set)                          #attach scrollbar action to scroll of canvas

        self.vsb.pack(side="right", fill="y")                                       #pack scrollbar to right of self
        self.canvas.pack(side="left", fill="both", expand=True)                     #pack canvas to left of self and expand to fil
        self.canvas_window = self.canvas.create_window((4,4), window=self.viewPort, anchor="nw",            #add view port frame to canvas
                                  tags="self.viewPort")

        self.viewPort.bind("<Configure>", self.onFrameConfigure)                       #bind an event whenever the size of the viewPort frame changes.
        self.canvas.bind("<Configure>", self.onCanvasConfigure)                       #bind an event whenever the size of the canvas frame changes.
            
        self.viewPort.bind('<Enter>', self.onEnter)                                 # bind wheel events when the cursor enters the control
        self.viewPort.bind('<Leave>', self.onLeave)                                 # unbind wheel events when the cursorl leaves the control

        self.onFrameConfigure(None)                                                 #perform an initial stretch on render, otherwise the scroll region has a tiny border until the first resize

    def onFrameConfigure(self, event):                                              
        '''Reset the scroll region to encompass the inner frame'''
        self.canvas.configure(scrollregion=self.canvas.bbox("all"))                 #whenever the size of the frame changes, alter the scroll region respectively.

    def onCanvasConfigure(self, event):
        '''Reset the canvas window to encompass inner frame when required'''
        canvas_width = event.width
        self.canvas.itemconfig(self.canvas_window, width = canvas_width)            #whenever the size of the canvas changes alter the window region respectively.

    def onMouseWheel(self, event):                                                  # cross platform scroll wheel event
        if platform.system() == 'Windows':
            self.canvas.yview_scroll(int(-1* (event.delta/120)), "units")
        elif platform.system() == 'Darwin':
            self.canvas.yview_scroll(int(-1 * event.delta), "units")
        else:
            if event.num == 4:
                self.canvas.yview_scroll( -1, "units" )
            elif event.num == 5:
                self.canvas.yview_scroll( 1, "units" )
    
    def onEnter(self, event):                                                       # bind wheel events when the cursor enters the control
        if platform.system() == 'Linux':
            self.canvas.bind_all("<Button-4>", self.onMouseWheel)
            self.canvas.bind_all("<Button-5>", self.onMouseWheel)
        else:
            self.canvas.bind_all("<MouseWheel>", self.onMouseWheel)

    def onLeave(self, event):                                                       # unbind wheel events when the cursorl leaves the control
        if platform.system() == 'Linux':
            self.canvas.unbind_all("<Button-4>")
            self.canvas.unbind_all("<Button-5>")
        else:
            self.canvas.unbind_all("<MouseWheel>")



# ********************************
# Example usage of the above class
# ********************************

class Example(tk.Frame):
    def __init__(self, root):

        tk.Frame.__init__(self, root)
        self.scrollFrame = ScrollFrame(self) # add a new scrollable frame.
        
        # Now add some controls to the scrollframe. 
        # NOTE: the child controls are added to the view port (scrollFrame.viewPort, NOT scrollframe itself)
        for row in range(100):
            a = row
            tk.Label(self.scrollFrame.viewPort, text="%s" % row, width=3, borderwidth="1", 
                     relief="solid").grid(row=row, column=0)
            t="this is the second column for row %s" %row
            tk.Button(self.scrollFrame.viewPort, text=t, command=lambda x=a: self.printMsg("Hello " + str(x))).grid(row=row, column=1)

        # when packing the scrollframe, we pack scrollFrame itself (NOT the viewPort)
        self.scrollFrame.pack(side="top", fill="both", expand=True)
    
    def printMsg(self, msg):
        print(msg)

if __name__ == "__main__":
    root=tk.Tk()
    Example(root).pack(side="top", fill="both", expand=True)
    root.mainloop()

I wanted to you both vertical and horizontal scrollbar . Its showing me scrollbar but not working

class ScrollFrame(tk.Frame):
def init(self):
super().init() # create a frame (self)

    self.canvas = tk.Canvas(self, borderwidth=0, background="#000000")          #place canvas on self
    self.viewPort = tk.Frame(self.canvas, background="#000000")                    #place a frame on the canvas, this frame will hold the child widgets
    self.vsb = tk.Scrollbar(self, orient="vertical", command=self.canvas.yview) #place a scrollbar on self
    self.hsb = tk.Scrollbar(self, orient=HORIZONTAL, command=self.canvas.xview)  # place a scrollbar on self
    self.canvas.configure(yscrollcommand=self.vsb.set,xscrollcommand=self.hsb.set)                          #attach scrollbar action to scroll of canvas
    #self.canvas.configure(xscrollcommand=self.hsb.set)
    self.vsb.pack(side="right", fill="y")                                       #pack scrollbar to right of self
    self.hsb.pack(side="bottom", fill=X)
    self.canvas.pack(side="right", fill="both", expand=True)                     #pack canvas to left of self and expand to fil
    self.canvas_window = self.canvas.create_window((0,0), window=self.viewPort, anchor="nw",            #add view port frame to canvas
                              tags="self.viewPort")

    self.viewPort.bind("<Configure>", self.onFrameConfigure)                       #bind an event whenever the size of the viewPort frame changes.
    self.canvas.bind("<Configure>", self.onCanvasConfigure)                       #bind an event whenever the size of the viewPort frame changes.

    self.onFrameConfigure(None)                                                 #perform an initial stretch on render, otherwise the scroll region has a tiny border until the first resize

def onFrameConfigure(self, event):
    '''Reset the scroll region to encompass the inner frame'''
    self.canvas.configure(scrollregion=self.canvas.bbox("all"))                 #whenever the size of the frame changes, alter the scroll region respectively.

def onCanvasConfigure(self, event):
    '''Reset the canvas window to encompass inner frame when required'''
    canvas_width = event.width
    self.canvas.itemconfig(self.canvas_window, width = canvas_width)            #whenever the size of the canvas chang

Thanks for the code:
One issue:

If i use another style from scrolbar two windows are opened:

from tkinter import ttk

style = ttk.Style()
style.theme_use('clam')

...
self.vsb = ttk.Scrollbar(self, orient="vertical", command=self.canvas.yview) #place a scrollbar on self 

What's wrong with that?

Hi, could you please help me with the frame in the canvas doesn't stretch to fill the canvas

@niteshgaba

See https://stackoverflow.com/questions/29319445/tkinter-how-to-get-frame-in-canvas-window-to-expand-to-the-size-of-the-canvas

@oddsun, the onCanvasConfigure is already there. I have fixed it by passing the height and width as a parameter.

@niteshgaba

See https://stackoverflow.com/questions/29319445/tkinter-how-to-get-frame-in-canvas-window-to-expand-to-the-size-of-the-canvas

Hi all,

First of all, thanks a lot for this really usefull scrollable frame class ! It helped me a lot and was for me the only working scrollable frame !!

But unfortunatelly I can't manage to use the scroll with the mouse-wheel even if my mouse pointer is on the bar... Is there a way to make it work ? It sends me this message in the console when I tried :

File "D:\Anaconda\lib\tkinter\__init__.py", line 1739, in yview res = self.tk.call(self._w, 'yview', *args) _tkinter.TclError: unknown option "": must be moveto or scroll

I found the answer to my question.

If anyone is interessed, here is a link to the fully working scrollFrame class with mousewheel:

https://stackoverflow.com/questions/68362391/using-mousewheel-on-scrollable-frame/68363151#68363151

@JeanBaptisteMelmi thanks for posting the solution. I have made it cross platform and added it to the gist so the above code should now support scrollwheel on all platforms.

never mind I figured it out. Thanks for posting this its really helpful!

Can you please tell me how you did it? Well, I couldn't

@oddsun thanks for finding the solution, however I can't seem to figure out how to use that solution in the original code. Could you explain how to use the solution to make the Scrollable Frame expand?

This is a wonderful solution for a scrollable frame. Thanks.

Thanks for this, what license is it under?

I too would like to know about the license. Are you OK with GPL 3+ distribution?

Sure, GPL 3+ is fine. Everything I write somehow relies on the work of others, so share and share alike. Credit to python and tkinter developers for their hard work on the language and toolkit. -- Source has been updated.

thanks you are a life saver, would have taken me ages to figure this out from scratch.

Thanks for sharing this reference implementation, which may be a variation or combination of other reference implementations. However, by putting it under the GPLv3 license, in theory any Python program with scrollable frames in a class with the methods shown must also be released under GPLv3 as a whole. Is that really what you intend?
Keep in mind that tkinter itself is under the much more permissive BSD license.

Thanks @peter88213 , You make a valid point. I only expect someone to share improvements they make to the original work. Larger works incorporating this code should not need to be open sourced. I have changed the license to something more permissive which allows larger works to remain closed source and differently licensed.

Created an account to commend @mp035 for sharing this code. Very, very useful, thanks!

Thanks @plifzig , much appreciated!

There is a bug when I add a few widgets on ScrollFrame (for example: for row in range(8): in line 81). And if I scroll up the ScrollFrame scrolls even though it shouldn't be.
This will be fixed if you change onMouseWheel method as follows:
def onMouseWheel(self, event): # cross platform scroll wheel event
if not (self.canvas.yview()[0] == 0.0 and event.delta > 0):
if platform.system() == 'Windows':
self.canvas.yview_scroll(int(-1 * (event.delta / 120)), "units")
elif platform.system() == 'Darwin':
self.canvas.yview_scroll(int(-1 * event.delta), "units")
else:
if event.num == 4:
self.canvas.yview_scroll(-1, "units")
elif event.num == 5:
self.canvas.yview_scroll(1, "units")
Tested on Windows

Hi @Anenokil , thanks for the comment, I tried the frame with 8 widgets on both windows 10 and linux (Manjaro) and I was unable to reproduce the issue you described. If you can provide more info, I'd be happy to look into it further.

I really have no idea what the reason could be. I just replaced 100 with 8, ran the program and scrolled up.
When I make the window large the effect disappears. But if you press any of the buttons and scroll, the effect appears again.
I use python 3.10.8 on Windows 10

video.mp4

Excellent video @Anenokil ! I think we may have different expectations of the preferred behavior. What I am seeing there is how I would expect the frame to behave. If I understand you correctly, you prefer scrolling to be disabled when the content is smaller than the viewport?

I get it, thanks @mp035. Indeed, we had different expectations.

To follow up on @Anenokil 's comment - my expectation was also that the frame would only scroll if items overflowed the frame vertically. I tried the solution proposed above but it did not work for me on Fedora Linux. What did work is the following:

def onMouseWheel(self, event: tk.Event):  # cross platform scroll wheel event
    canvas_height = self.canvas.winfo_height()
    rows_height = self.canvas.bbox("all")[3]

    if rows_height > canvas_height: # only scroll if the rows overflow the frame
        if platform.system() == 'Windows':
            self.canvas.yview_scroll(int(-1* (event.delta/120)), "units")
        elif platform.system() == 'Darwin':
            self.canvas.yview_scroll(int(-1 * event.delta), "units")
        else:
            if event.num == 4:
                self.canvas.yview_scroll( -1, "units" )
            elif event.num == 5:
                self.canvas.yview_scroll( 1, "units" )

Hope this helps someone in the future!

I just learned something which may help someone having problems with the width of the ScrollFrame. Apologies if I misuse some technical tkinter terms. I'm new to this and it took hours just to figure out the seven levels of nested widgets that make this work (root, Example, scrollFrame, canvas and vsb, viewPort and canvas_window, and then the Labels and Buttons).

My application has a grid with one row and 3 columns. The middle column contains a ScrollFrame, and it was coming out much wider than the widgets it contained. Those widgets were simply a column of buttons about 170 pixels wide.

Then I ran the built-in Example and found the same problem. The displayed window would have the labels and buttons, and then a lot of wasted space to the right. It is possible to squeeze this space away by guessing and specifying a window width, but that seemed wrong. In the screenshot I turned the viewPort background yellow to make this more visible.

Normally widgets are a tight fit in their containers unless otherwise specified, but not in this case. You have to use something like
self.scrollFrame.canvas.configure(width=maxW) where maxW is the width of your contained widgets.

To show this in the provided code I built lists of the labels and buttons as they were built, because their width isn't available until later. Then after the items are created and pack is called at line 89 I added this:

        self.scrollFrame.update()  # trigger sizing!  Only now are button and label sizes valid.
        maxW = 0;
        for row in range(21):
            maxW = max(maxW, labList[row].winfo_width() + bList[row].winfo_width())
        self.scrollFrame.canvas.configure(width=maxW) # works!

It would have been enough to check just the last row in this case, but this seems more flexible. It's simpler in my application because I know the exact width of the buttons in advance. There may be a need to adjust the resulting value a little if there is padding or some other reason that more space is needed.

In case it matters I'm running Python 3.10.9 in Spyder 5.4.2 on Windows 11.

This is really solid. Have you ever considered adding this to PIP? I don't mind doing it if you would like.

Thanks. It's just a single file, so I don't really see the need to package it. It's open source, so you're free to do whatever you want with it, but can I please ask that you credit, or provide a link to this gist. Have a great day.