Web Analytics Made Easy - Statcounter
Skip to content

The Elements

Recall from the "Getting Started" section that a "layout" defines the contents of your Window and a layout is a list of lists of Elements. This section describes each of the Elements that you'll find in the tkinter port.

These are the 34 Elements you can use to build your window's layout.


You will find detailed parameter information on Elements located in the Call Reference Tab of the documentation.

"Elements" are the building blocks used to create windows. Some GUI APIs use the term "Widget" to describe these user interface building blocks. In PySimpleGUI the term Element is used so that it's clear when a PySimpleGUI Element is being referenced versus an underlying GUI Framework's Widget.

PySimpleGUI Elements are implemented using to a GUI Framework Widget, usually in a 1-to-1 manner. For example, a Text Element is implemented in tkinter using a Label Widget.

Sometimes Elements are created by combining PySimpleGUI Elements. For example, the Titlebar and MenubarCustom are Elements that are implemented by PySimpleGUI by using other elements.

KEYS - Very Important...

There is one specific concept of elements that is critical you understand when reading this description and chat concept is keys.They've been described earlier in the documentation and you'll find a complete description of keys in this section:


For now, you should understand that an Element can have a key, a unique identifier for that specific Element. A key can be an int, a string, a tuple, ...., but not a list. Any "hashable" value is allowed. They are often strings, and the PySimpleGUI coding conventions suggests string keys use the format '-KEY-'. Tuples are a very useful datatype to use for keys as well so spend some time studying this concept!

Table of Elements in Tkinter Port

Each port of PySimpleGUI has a core set of Elements as well as port-specific elements. Some port-specific elements include the Dial element in the Qt port, and the Pane element in the tkinter port.

Element Name Aliases tkinter Widget Description
Text T, Txt tk.Label One or more lines of Text
Input I, In, InputText tk.Entry Single line text input
Combo DD, Drop, DropDown, InputCombo ttk.Combobox A "Dropdown" list that can be edited too
OptionMenu InputOptionMenu tk.OptionMenu Like a Combo
Multiline ML, MLine tk.Text or tk.scrolledtext.ScrolledText Multiple lines of text for input or output
Output tk.Text (sorta) Not suggested. Multiline is better choice. Re-routes stdout
Radio R, Rad tk.Radiobutton Radio Buttons - choose 1 from several
Checkbox CB, CBox, Check tk.Checkbutton Checkbox - binary choice Yes/No
Spin Sp tk.Spinbox Choose 1 by using arrows. Can manually enter also
Button B, Btn tk.Button or ttk.Button Button - plain or with image
Image Im tk.Label A PNG or GIF image
Canvas tk.Canvas A drawing area. Graph may be batter to use
Column Col Combination Canvas & Frame Embeds layouts inside layouts
Frame Fr tk.LabelFrame A frame with a title and a border
Tab tk.Frame Container used with TabGroup
TabGroup ttk.Notebook Holds Tabs in layouts
Pane tk.PanedWindow Sliding columns (it's kinda weird but useful)
Graph G tk.Canvas A drawing area with primitives
Slider Sl tk.Scale Slider to choose from range of choices
Listbox LB, LBox tk.Listbox Listbox - a list of choices
Menu MenuBar, Menubar tk.Menu A standard Menubar
MenubarCustom Combined Elements Custom colors and font for menubar
ButtonMenu BM, BMenu tk.Menubutton Button that shows a menu
Titlebar Combined Elements Custom colors for a titlebar
ProgressBar PBar, Prog, Progress ttk.Progressbar
Table ttk.Treeview A table with clickible cells and headers
Tree ttk.Treeview A tree with collapsible sections
VerticalSeparator VSep, VSeparator ttk.Separator Vertical line
HorizontalSeparator HSep, HSeparator ttk.Separator Horizontal line
StatusBar SBar tk.Label Statusbar for bottom of window
Sizegrip SGrip ttk.Sizegrip A grip for the bottom right corner of a window
Push P, Stretch PySimpleGUI Elements Pushes elements horizontally
VPush VP, VStretch PySimpleGUI Elements Pushes rows vertically
Sizer Column Element Creates a Width x Height number of pixels for padding/sizing

The "All Elements" Demo Program

The Window shown above was created using this code that is a Demo Program named Demo_Program_All_Elements_Simple.py:

import PySimpleGUI as sg

    Demo - Element List

    All elements shown in 1 window as simply as possible.

    Copyright 2022 PySimpleGUI

use_custom_titlebar = True if sg.running_trinket() else False

def make_window(theme=None):

    NAME_SIZE = 23

    def name(name):
        dots = NAME_SIZE-len(name)-2
        return sg.Text(name + ' ' + '•'*dots, size=(NAME_SIZE,1), justification='r',pad=(0,0), font='Courier 10')


    # NOTE that we're using our own LOCAL Menu element. It can be the standard Menubar or the PySimpleGUI MenubarCustom
    if use_custom_titlebar:
        Menu = sg.MenubarCustom
        Menu = sg.Menu

    treedata = sg.TreeData()

    treedata.Insert("", '_A_', 'Tree Item 1', [1234], )
    treedata.Insert("", '_B_', 'B', [])
    treedata.Insert("_A_", '_A1_', 'Sub Item 1', ['can', 'be', 'anything'], )

    layout_l = [[name('Text'), sg.Text('Text')],
                [name('Input'), sg.Input(s=15)],
                [name('Multiline'), sg.Multiline(s=(15,2))],
                [name('Output'), sg.Output(s=(15,2))],
                [name('Combo'), sg.Combo(sg.theme_list(), default_value=sg.theme(), s=(15,22), enable_events=True, readonly=True, k='-COMBO-')],
                [name('OptionMenu'), sg.OptionMenu(['OptionMenu',],s=(15,2))],
                [name('Checkbox'), sg.Checkbox('Checkbox')],
                [name('Radio'), sg.Radio('Radio', 1)],
                [name('Spin'), sg.Spin(['Spin',], s=(15,2))],
                [name('Button'), sg.Button('Button')],
                [name('ButtonMenu'), sg.ButtonMenu('ButtonMenu', sg.MENU_RIGHT_CLICK_EDITME_EXIT)],
                [name('Slider'), sg.Slider((0,10), orientation='h', s=(10,15))],
                [name('Listbox'), sg.Listbox(['Listbox', 'Listbox 2'], no_scrollbar=True,  s=(15,2))],
                [name('Image'), sg.Image(sg.EMOJI_BASE64_HAPPY_THUMBS_UP)],
                [name('Graph'), sg.Graph((125, 50), (0,0), (125,50), k='-GRAPH-')]  ]

    layout_r  = [[name('Canvas'), sg.Canvas(background_color=sg.theme_button_color()[1], size=(125,40))],
                [name('ProgressBar'), sg.ProgressBar(100, orientation='h', s=(10,20), k='-PBAR-')],
                [name('Table'), sg.Table([[1,2,3], [4,5,6]], ['Col 1','Col 2','Col 3'], num_rows=2)],
                [name('Tree'), sg.Tree(treedata, ['Heading',], num_rows=3)],
                [name('Horizontal Separator'), sg.HSep()],
                [name('Vertical Separator'), sg.VSep()],
                [name('Frame'), sg.Frame('Frame', [[sg.T(s=15)]])],
                [name('Column'), sg.Column([[sg.T(s=15)]])],
                [name('Tab, TabGroup'), sg.TabGroup([[sg.Tab('Tab1',[[sg.T(s=(15,2))]]), sg.Tab('Tab2', [[]])]])],
                [name('Pane'), sg.Pane([sg.Col([[sg.T('Pane 1')]]), sg.Col([[sg.T('Pane 2')]])])],
                [name('Push'), sg.Push(), sg.T('Pushed over')],
                [name('VPush'), sg.VPush()],
                [name('Sizer'), sg.Sizer(1,1)],
                [name('StatusBar'), sg.StatusBar('StatusBar')],
                [name('Sizegrip'), sg.Sizegrip()]  ]

    # Note - LOCAL Menu element is used (see about for how that's defined)
    layout = [[Menu([['File', ['Exit']], ['Edit', ['Edit Me', ]]],  k='-CUST MENUBAR-',p=0)],
              [sg.T('PySimpleGUI Elements - Use Combo to Change Themes', font='_ 14', justification='c', expand_x=True)],
              [sg.Checkbox('Use Custom Titlebar & Menubar', use_custom_titlebar, enable_events=True, k='-USE CUSTOM TITLEBAR-', p=0)],
              [sg.Col(layout_l, p=0), sg.Col(layout_r, p=0)]]

    window = sg.Window('The PySimpleGUI Element List', layout, finalize=True, right_click_menu=sg.MENU_RIGHT_CLICK_EDITME_VER_EXIT, keep_on_top=True, use_custom_titlebar=use_custom_titlebar)

    window['-PBAR-'].update(30)                                                     # Show 30% complete on ProgressBar
    window['-GRAPH-'].draw_image(data=sg.EMOJI_BASE64_HAPPY_JOY, location=(0,50))   # Draw something in the Graph Element

    return window

window = make_window()

while True:
    event, values = window.read()
    if event == sg.WIN_CLOSED or event == 'Exit':

    if values['-COMBO-'] != sg.theme():
        window = make_window()
    if event == '-USE CUSTOM TITLEBAR-':
        use_custom_titlebar = values['-USE CUSTOM TITLEBAR-']
        window = make_window()
    if event == 'Edit Me':
    elif event == 'Version':
        sg.popup_scrolled(__file__, sg.get_versions(), location=window.current_location(), keep_on_top=True, non_blocking=True)

The code is provided here so that you can see that only 73 lines of code are required to show all 34 elements in 1 window. Normally only 1 line of code is required to show an element in your window, but this code includes logic that allows you to see the standard titlebar and menubar as well as the PySimpleGUI custom titlebar and custom menubar.

You can preview all of the PySimpleGUI Themes with this program to see how each element will appear using a particular theme. For example, this window uses the "Dark Gray 15" theme and is using a custom titlebar and a custom menubar.


Try It For Yourself

This Trinket uses the latest release of PySimpleGUI with the same basic code above.


Some of the Elements are implemented using a function that returns an element, often a a Column element. Some examples are TitleBar, MenubarCustom, and Push. Because these are not created using Python classes they can be possibly confusing if you are using an IDE with code completion and are looking for a class rather than a function.. All of the "Browse" buttons are Pseudo-elements. For example, BrowseFile is a function that returns a Button object.

You'll also find the term "User Defined Elements" throughout all PySimpleGUI materials including the Demo Programs. This term means the same thing. It's a function that returns one or more elements.

Container Elements

Container elements are how you embed layouts within a window. A container element "contains" rows of elements just like a Window does. Container elements include:

  • Column
  • Frame
  • Tab

These elements can be used to expand a window's contents after the window is created and perform operations on groups of elements. See the layout section for more information on dynamic layouts.