Customize Color Palettes#

The panel-material-ui palette system allows you to customize component colors to suit your brand. Colors are grouped into default categories (primary, secondary, error, warning, info, success) or custom categories that you define yourself.

Color tokens#

In panel-material-ui, each color typically has up to four tokens:

  • main: The primary “shade” of the color

  • light: A lighter variant of main

  • dark: A darker variant of main

  • contrastText: A color intended to contrast well against main (usually text)

For example, the default primary color might look like:

primary = {
  'main': '#1976d2',
  'light': '#42a5f5',
  'dark': '#1565c0',
  'contrastText': '#fff',
}

To learn more about the theory behind these tokens, check out the Material Design color system.

Default colors#

panel-material-ui provides nine default palette categories you can customize:

  • default

  • primary

  • secondary

  • error

  • warning

  • info

  • success

  • dark

  • light

Each has the same four tokens (main, light, dark, contrastText). These defaults are enough for most apps, but you can add custom palette entries as needed.

Customizing the default palette#

You can override the defaults via the theme_config parameter that you pass to your panel-material-ui components:

from panel_material_ui import Button

my_theme = {
    "palette": {
        "primary": {
            "main": "#ff69b4", # Changed to pink
            "light": "#42a5f5",
            "dark": "#1565c0",
            "contrastText": "#fff",
        },
        "secondary": {
            "main": "#f44336",
        },
    }
}

Button(label="Custom Themed Button", theme_config=my_theme, button_type='primary')



            
            


Important


Palette colors must be specified as hex, rgb(), rgba(), hsl() or hsla() strings. Named CSS colors such as "teal" are not supported by Material UI’s color manipulation functions and will raise an error.






Providing colors directly#


You don’t need to use a predefined palette. For each palette entry (e.g., primary), you can specify main (required), and optionally light, dark, and contrastText:


from panel_material_ui import Button, Row

my_theme = {
    "palette": {
        "primary": {
            "main": "#ff69b4", # Changed to pink
            # light, dark, and contrastText can be automatically computed
        },
        "secondary": {
            "main": "#E0C2FF",
            "light": "#F5EBFF",   # optional
            "dark": "#BA99D5",    # optional
            "contrastText": "#47008F",  # optional
        }
    }
}

Row(
    Button(label="Primary", theme_config=my_theme, button_type='primary'),
    Button(label="Secondary", theme_config=my_theme, button_type='secondary'),
)







            
            




Contrast threshold#


When panel_material_ui automatically picks contrastText for a color (if you don’t specify it), it uses a contrastThreshold value. By default, it’s 3 (a 3:1 contrast), but you can increase it for improved accessibility:


my_theme = {
    "palette": {
        "primary": {
            "main": "#3f50b5",
        },
        "contrastThreshold": 4.5  # Increase for higher contrast
    }
}





This helps ensure a better color contrast ratio for text displayed over the primary.main color.






Tonal offset#


Similarly, panel_material_ui calculates the light and dark tokens by shifting the luminance of main. The tonalOffset defaults to 0.2, but you can override it at the top level of your palette:


my_theme = {
    "palette": {
        "tonalOffset": 0.25,
        "primary": {
            "main": "#FF5733",
        },
    }
}





This means light becomes lighter and dark becomes darker relative to main.






Accessibility#


For color contrast, the recommendation is a minimum ratio of 4.5:1 for body text (per WCAG 2.1 Rule 1.4.3). If you’re relying on panel_material_ui to auto-compute contrastText, be sure to increase contrastThreshold to 4.5:


my_theme = {
    "palette": {
        "contrastThreshold": 4.5,
        "primary": {"main": "#3f50b5"},
    }
}





However, you should still verify that the chosen foreground and background colors yield the contrast you want, especially if you’re targeting stricter guidelines.








Dark mode#


For more guidance on setting up dark mode, including toggling, see our Dark mode guide. Typically, in panel_material_ui, you either set dark_theme=True on individual components or at the Page level. To use a separate palette in dark mode, nest the palette under "light" and "dark" keys in the theme_config.






Summary#


    

  • Default palette: default, primary, secondary, error, warning, info, success, light, dark
    • 

  • Custom palette: define your own named colors (e.g., ochre, violet)
    • 

  • Tokens: main, light, dark, contrastText (and optionally more)
    • 

  • Automatic computations: If you only specify main, panel-material-ui tries to infer light, dark, and contrastText using contrastThreshold and tonalOffset.
    • 

  • Accessibility: Increase contrastThreshold if you need a higher text contrast ratio.
    • 

  • Color format: hex, rgb() or hsl() strings, not CSS color names
    • 

  • Dark mode: Supply a mode-specific theme_config with "light" and "dark" keys and set dark_theme=True to enable dark mode.
    • 



With panel-material-ui, you have the full flexibility to define or override any palette color you need—at a component level using theme_config or globally across your entire application.