Creating themes

pygame-menu offers many parameters to control the visual aspect of the menu. For an easier usage, all of them are gathered in a specific object called a theme. It is used to customize the menu window itself and all its widgets.

menu = pygame_menu.Menu(


The theme parameters can be overwritten locally when adding a widget to the menu. See the overwritable ones in the add… methods

Default themes

Several predefined themes are proposed by pygame-menu.

Theme name














Create a theme

If none of the proposed theme fit to the needs, the Theme give the opportunity to create custom themes.

mytheme = Theme(background_color=(0, 0, 0, 0), # transparent background
                title_background_color=(4, 47, 126),

menu = Menu(..., theme=mytheme)

Of course it is also possible to start from a predefined theme by copying it first.

mytheme = pygame_menu.themes.THEME_ORANGE.copy()
mytheme.title_background_color=(0, 0, 0)

menu = Menu(..., theme=mytheme)


The alignment (str) can take one of the three following values:




Left alignment


Center alignment


Right alignment

Background Color/Images

Theme background can be both a color or an image. All colors can be defined using a tuple or a list of 3 or 4 numbers between 0 and 255. The format of the numbers are:

color_opaque = (R, G, B)
color_transparent = (R, G, B, A)

A alpha channels goes from 0 to 255. 0 is transparent, 255 is opaque. For using images as a background color, class pygame_menu.baseimage.BaseImage must be used.

Images needs a Path (file location on disk), a drawing mode, and an optional offset.

myimage = pygame_menu.baseimage.BaseImage(
mytheme.background_color = myimage

Image drawing modes



Centers the image in the surface


Fill the image on the surface


Repeat the image on x axis


Repeat the image on x and y axis


Repeat the image on y axis


Write the image on top-left location

Currently, Theme class only supports images for background_color and widget_background_color. Also, only IMAGE_MODE_FILL drawing mode is valid for widget_background_color.


This library also has some fonts to use (TTF format). To load a font, run this code:

import pygame_menu

font = pygame_menu.font.FONT_NAME
my_theme = Theme(widget_font=font, ...)

Available fonts






































System fonts can also be used. The available system fonts can be listed using the following command in a python shell:

import pygame


Several possible positions are accepted by some configurations:




East position


North position


North/East position


North/West position


South position


South/East position


South/West position


West position

Special positions used by Menu pygame_menu._scrollarea.ScrollArea (all above are available):




Scroll on both X axis


Scroll on both Y axis


Scroll on both X and Y axis

Widget selection effect

A selection effect is a drawing class used to define the way to highlight the focused widget. An instance of the selection effect class is defined in the Theme.widget_selection_effect Theme property. See example on how to add a selection effect in Create a selection effect chapter.

The available selection effects are:


Selection effect


Rectangular highlight


Left arrow on the widget


No selection


Right arrow on the widget


Only font color is changed

The selection color is defined in Theme.widget_selection_color.

Theme API

class pygame_menu.themes.Theme(**kwargs)[source]

Class defining the visual rendering of menus and widgets.


All colors must be defined with a tuple of 3 or 4 numbers in the formats:

  • (R, G, B)

  • (R, G, B, A)

Red (R), Green (G), and Blue (B) must be numbers between 0 and 255. A means the alpha channel (opacity), if 0 the color is transparent, 100 means opaque.


Themes only modify visual behaviour of the Menu. For other options like rows/columns, enabling or disabling overflow, position, or Menu width/height see Menu parameters.

  • background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage) – Menu background color

  • border_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage, None) – Menu border color. If border is an image, it will be split in 9 tiles to use top, left, bottom, right, and the corners

  • border_width (int) – Border width in px. Used only if border_color is not an image

  • cursor_color (tuple, list, str, int, pygame.Color) – Cursor color (used in some text-gathering widgets like TextInput)

  • cursor_selection_color (tuple, list, str, int, pygame.Color) – Color of the text selection if the cursor is enabled on certain widgets

  • cursor_switch_ms (int, float) – Interval of cursor switch between off and on status

  • focus_background_color (tuple, list, str, int, pygame.Color) – Color of the widget focus, this must be a tuple of 4 elements (R, G, B, A)

  • fps (int, float) – Menu max fps (frames per second). If 0 there’s no limit

  • readonly_color (tuple, list, str, int, pygame.Color) – Color of the widget in readonly mode

  • readonly_selected_color (tuple, list, str, int, pygame.Color) – Color of the selected widget in readonly mode

  • scrollarea_outer_margin (tuple, list) – Outer ScrollArea margin in px; the tuple is added to computed ScrollArea width/height, it can add a margin to bottom/right scrolls after widgets. If value less than 1 use percentage of width/height. It cannot be a negative value

  • scrollarea_position (str) – Position of ScrollArea scrollbars. See pygame_menu.locals

  • scrollbar_color (tuple, list, str, int, pygame.Color) – Scrollbars color

  • scrollbar_cursor (int, pygame.cursors.Cursor, None) – Scrollbar cursor if mouse is placed over. If None the scrollbar don’t change the cursor

  • scrollbar_shadow (bool) – Indicate if a shadow is drawn on each scrollbar

  • scrollbar_shadow_color (tuple, list, str, int, pygame.Color) – Color of the scrollbar shadow

  • scrollbar_shadow_offset (int) – Offset of the scrollbar shadow

  • scrollbar_shadow_position (str) – Position of the scrollbar shadow. See pygame_menu.locals

  • scrollbar_slider_color (tuple, list, str, int, pygame.Color) – Color of the sliders

  • scrollbar_slider_hover_color (tuple, list, str, int, pygame.Color) – Color of the slider if hovered or clicked

  • scrollbar_slider_pad (int, float) – Space between slider and scrollbars borders

  • scrollbar_thick (int) – Scrollbar thickness in px

  • selection_color (tuple, list, str, int, pygame.Color) – Color of the selected widget. It updates both selected font and widget_selection_effect color

  • surface_clear_color (tuple, list, str, int, pygame.Color) – Surface clear color before applying background function

  • title (bool) – Title is enabled/disabled. If disabled the object is hidden

  • title_background_color (tuple, list, str, int, pygame.Color) – Title background color

  • title_bar_modify_scrollarea (bool) – If True title bar modifies the scrollbars of the scrollarea depending on the style

  • title_bar_style (int) – Style of the title, use pygame_menu.widgets.MenuBar widget styles

  • title_close_button (bool) – Draw a back-box button on header to close the Menu. If user moves through nested submenus this buttons turns to a back-arrow

  • title_close_button_background_color (tuple, list, str, int, pygame.Color) – Title back-box background color

  • title_close_button_cursor (int, pygame.cursors.Cursor, None) – Cursor applied over title close button

  • title_fixed (bool) – If True title is drawn over the scrollarea, forcing widget surface area to be drawn behind the title

  • title_floating (bool) – If True title don’t contribute height to the Menu. Thus, scroll uses full menu width/height

  • title_font (str, pygame.font.Font, pathlib.Path) – Title font

  • title_font_antialias (bool) – Title font renders with antialiasing

  • title_font_color (tuple, list, str, int, pygame.Color) – Title font color

  • title_font_shadow (bool) – Enable title font shadow

  • title_font_shadow_color (tuple, list, str, int, pygame.Color) – Title font shadow color

  • title_font_shadow_offset (int) – Offset of title font shadow in px

  • title_font_shadow_position (str) – Position of the title font shadow. See pygame_menu.locals

  • title_font_size (int) – Font size of the title

  • title_offset (tuple, list) – Offset (x-position, y-position) of title in px

  • title_updates_pygame_display (bool) – If True the menu title updates See pygame.display.caption automatically on draw

  • widget_alignment (str) –

    Widget default alignment. See pygame_menu.locals

  • widget_alignment_ignore_scrollbar_thickness (bool) – Widget positioning ignores the scrollbar thickness. If True, the widgets only consider the menu size, ignoring the thickness of the visible scrollbars

  • widget_background_color (tuple, list, str, int, pygame.Color, pygame_menu.baseimage.BaseImage, None) – Background color of a widget, it can be a color, None (transparent), or a BaseImage object. Background fills the entire widget + the padding

  • widget_background_inflate (tuple, list) – Inflate background on x-axis and y-axis (x, y) in px. By default, it uses the highlight margin. This parameter is visual only. For modifying widget size use padding instead

  • widget_background_inflate_to_selection (bool) – If True widget will inflate to match selection effect margin and overrides widget_background_inflate

  • widget_border_color (tuple, list, str, int, pygame.Color) – Widget border color

  • widget_border_inflate (tuple, list) – Widget inflate size on x-axis and y-axis (x, y) in px. These values cannot be negative

  • widget_border_position (str, tuple, list) – Widget border positioning. It can be a single position, or a tuple/list of positions. Only are accepted: north, south, east, and west. See pygame_menu.locals

  • widget_border_width (int) – Widget border width in px. If 0 the border is disabled. Border width don’t contribute to the widget width/height, it’s visual-only

  • widget_box_arrow_color (tuple, list, str, int, pygame.Color) – Widget box arrow color, used by some widgets such as DropSelect, Fancy Selector, etc.

  • widget_box_arrow_margin (tuple) – Widget box arrow margin (left, right, vertical) in px, used by some widgets such as DropSelect, Fancy Selector, etc.

  • widget_box_background_color (tuple, list, str, int, pygame.Color) – Widget box background color, used by some widgets such as DropSelect, Fancy Selector, etc.

  • widget_box_border_color (tuple, list, str, int, pygame.Color) – Widget box border color, used by some widgets such as DropSelect, Fancy Selector, etc.

  • widget_box_border_width (int) – Widget box border width in px, used by some widgets such as DropSelect, Fancy Selector, etc.

  • widget_box_inflate (tuple, list) – Widget box inflate on x-axis and y-axis (x, y) in px, used by some widgets such as DropSelect, Fancy Selector, etc.

  • widget_box_margin (tuple, list) – Box margin on x-axis and y-axis (x, y) in px

  • widget_cursor (int, pygame.cursors.Cursor, None) – Widget cursor if mouse is placed over. If None the widget don’t change the cursor

  • widget_font (str, pygame.font.Font, pathlib.Path) – Widget font path or name

  • widget_font_antialias (bool) – Widget font renders with antialiasing

  • widget_font_background_color (tuple, list, str, int, pygame.Color, None) – Widget font background color. If None the value will be the same as background_color if it is a color object and if widget_font_background_color_from_menu is True and widget_background_color is None

  • widget_font_background_color_from_menu (bool) – Use Menu background color as font background color. Disabled by default

  • widget_font_color (tuple, list, str, int, pygame.Color) – Color of the font

  • widget_font_shadow (bool) – Indicate if the widget font shadow is enabled

  • widget_font_shadow_color (tuple, list, str, int, pygame.Color) – Color of the widget font shadow

  • widget_font_shadow_offset (int) – Offset of the widget font shadow in px

  • widget_font_shadow_position (str) – Position of the widget font shadow. See pygame_menu.locals

  • widget_font_size (int) – Font size

  • widget_margin (tuple, list) – Horizontal and vertical margin of each element in Menu in px

  • widget_padding (int, float, tuple, list) – Padding of the widget according to CSS rules. It can be a single digit, or a tuple of 2, 3, or 4 elements. Padding modifies widget width/height

  • widget_offset (tuple, list) – x-axis and y-axis (x, y) offset of widgets within Menu in px respect to top-left corner. If value less than 1 use percentage of width/height. It cannot be a negative value

  • widget_selection_effect (pygame_menu.widgets.core.Selection, None) – Widget selection effect object. This is visual-only, the selection properties does not affect widget height/width

  • widget_shadow_aa (int) – Widget shadow antialiasing factor, default is x4

  • widget_shadow_color (tuple, list, str, int, pygame.Color) – The color of the widget shadow

  • widget_shadow_radius (int) – The border radius of the widget shadow

  • widget_shadow_type (str) – The shadow type, it can be ‘rectangular’ or ‘ellipse’

  • widget_shadow_width (int) – The width of the shadow in px

  • widget_tab_size (int) – Widget tab size

  • widget_url_color (tuple, list, str, int, pygame.Color) – Color of url text links


Creates a deep copy of the object.

Return type:



Copied theme


Modify the Menu background color with given opacity.


opacity (float) – Opacity value, from 0 (transparent) to 1 (opaque)

Return type:



Self reference


Validate the values of the theme. If there’s an invalid parameter throws an AssertionError.

This function also converts all lists to tuples. This is done because lists are mutable.

Return type:



Self reference