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, pygame_menu.baseimage.BaseImage) – Menu background color

  • 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 changes 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 contributes 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_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 contributes 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 changes 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’s 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) – Widget selection effect object. This is visual-only, the selection properties does not affect widget height/width

  • 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 a invalid parameter throws an AssertionError.

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

Return type



Self reference