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(300, 400,


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 Example
pygame_menu.themes.THEME_DEFAULT ../_images/theme_default.png
pygame_menu.themes.THEME_BLUE ../_images/theme_blue.png
pygame_menu.themes.THEME_DARK ../_images/theme_dark.png
pygame_menu.themes.THEME_GREEN ../_images/theme_green.png
pygame_menu.themes.THEME_ORANGE ../_images/theme_orange.png
pygame_menu.themes.THEME_SOLARIZED ../_images/theme_solarized.png

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)

Background Color/Images

Theme background can be both a color or an image. All colors can be defined using a tuple or an list of 3 or 4 numbers between 0 and 255. The format of numers 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 Description
pygame_menu.baseimage.IMAGE_MODE_CENTER Centers the image in the surface
pygame_menu.baseimage.IMAGE_MODE_FILL Fill the image on the surface
pygame_menu.baseimage.IMAGE_MODE_REPEAT_X Repeat the image on x axis
pygame_menu.baseimage.IMAGE_MODE_REPEAT_XY Repeat the image on x and y axis
pygame_menu.baseimage.IMAGE_MODE_REPEAT_Y Repeat the image on y axis
pygame_menu.baseimage.IMAGE_MODE_SIMPLE 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.

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 parameter of a theme. See example on how to add a selection effect in Create a selection effect chapter.

The available selection effects are:

Class Selection effect
pygame_menu.widgets.HighlightSelection Rectangular highlight
pygame_menu.widgets.LeftArrowSelection Left arrow on the widget
pygame_menu.widgets.NoneSelection No selection
pygame_menu.widgets.RightArrowSelection Right arrow on the widget

The selection color is defined in Theme.widget_selection_color.


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

import pygame_menu

font = pygame_menu.font.FONT_NAME
my_theme = Theme(widget_font=font, ...)
Available fonts Preview
pygame_menu.font.FONT_8BIT ../_images/font_8bit.png
pygame_menu.font.FONT_BEBAS ../_images/font_bebas.png
pygame_menu.font.FONT_COMIC_NEUE ../_images/font_comic_neue.png
pygame_menu.font.FONT_FRANCHISE ../_images/font_franchise.png
pygame_menu.font.FONT_HELVETICA ../_images/font_helvetica.png
pygame_menu.font.FONT_MUNRO ../_images/font_munro.png
pygame_menu.font.FONT_NEVIS ../_images/font_nevis.png
pygame_menu.font.FONT_OPEN_SANS ../_images/font_open_sans.png
pygame_menu.font.FONT_OPEN_SANS_BOLD ../_images/font_open_sans_bold.png
pygame_menu.font.FONT_OPEN_SANS_ITALIC ../_images/font_open_sans_italic.png
pygame_menu.font.FONT_OPEN_SANS_LIGHT ../_images/font_open_sans_light.png
pygame_menu.font.FONT_PT_SERIF ../_images/font_pt_serif.png

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

import pygame

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) – Color of cursor
  • cursor_selection_color (tuple, list) – Selection box color
  • focus_background_color (tuple, list) – Color of the widget focus, this must be a tuple of 4 elements. Also must be transparent
  • menubar_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
  • scrollarea_outer_margin (tuple, list) – Outer scoll area margin (px), the tuple is added to computed scroll area width/height, it can add an margin to bottom/right scrolls after widgets. If value less than 1 use percentage of width/height. Default (0,0). It cannot be negative values
  • scrollbar_color (tuple, list) – Scrollbars color
  • scrollbar_shadow (bool) – Indicate if a shadow is drawn on each scrollbar
  • scrollbar_shadow_color (tuple, list) – Color of the scrollbar shadow
  • scrollbar_shadow_offset (int, float) – Offset of the scrollbar shadow
  • scrollbar_shadow_position (str) – Position of the scrollbar shadow. See pygame_menu.locals
  • scrollbar_slider_color (tuple, list) – Color of the sliders
  • scrollbar_slider_pad (int, float) – Space between slider and scrollbars borders
  • scrollbar_thick (int, float) – Scrollbar thickness
  • selection_color (tuple, list) – Color of the selected widget, it affects font color and the selection effect
  • surface_clear_color (tuple, list) – Surface clear color before applying background function
  • title_background_color (tuple, list) – Title background color
  • title_bar_style (int) – Style of the title, use menubar widget styles
  • title_font (str, None) – Title font color. If None use the widget font color
  • title_font_antialias (bool) – Title font renders with antialiasing
  • title_font_color (tuple, list, None) – Title font color, if None use the widget font color
  • title_font_size (int) – Font size of the title
  • title_offset (tuple, list) – Offset (x-position,y-position) of title (px). Default (0,0)
  • title_shadow (bool) – Enable shadow on title
  • title_shadow_color (tuple, list) – Title shadow color
  • title_shadow_offset (int, float) – Offset of shadow on title
  • title_shadow_position (str) – Position of the shadow on title. See pygame_menu.locals
  • widget_alignment (str) – Widget default alignment
  • widget_background_color (tuple, list, pygame_menu.baseimage.BaseImage, None) – Background color of a widget, it can be a color or a BaseImage object. Background fills the entire widget + the padding
  • widget_background_inflate (tuple, list) – Inflate background in (x,y) in px. By default it uses the highlight margin. This parameter is visual only. For modifying widget size use padding instead
  • widget_font (str) – Widget font path or name
  • widget_font_antialias (bool) – Widget font renders with antialiasing
  • widget_font_background_color (tuple, list, None) – Widget font background color. By default it is None. 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) – Color of the font
  • widget_font_size (int) – Font size
  • widget_margin (tuple, list) – Horizontal and vertical margin of each element in Menu (px). Default (0,10)
  • 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, y) axis offset of widgets within Menu (px) respect to top-left corner. If value less than 1 use percentage of width/height. Default (0,0). It cannot be negative values
  • 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_shadow (bool) – Indicate if the widget text shadow is enabled
  • widget_shadow_color (tuple, list) – Color of the widget shadow
  • widget_shadow_offset (int, float) – Offset of the widget shadow
  • widget_shadow_position (str) – Position of shadow. See pygame_menu.locals

Creates a deep copy of the object.

Returns:Copied theme
Return type:Theme

Modify menu background color with given opacity.

Parameters:opacity (int) – Opacity value, from 0 (transparent) to 1 (transparent)

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.