ColorMap#

Download this notebook from GitHub (right-click to download).

This component replaces a classic Panel component

This component is being integrated into Panel. Starting with Panel 1.10 it is available as pn.ui.ColorMap, documented in the Panel reference, and supersedes the classic pn.widgets.ColorMap. On Panel 1.10 and later, prefer the panel.ui namespace.

import panel as pn
import panel_material_ui as pmui

pn.extension()

The ColorMap widget selects a colormap from a dictionary of named palettes. Each option is displayed as a color gradient, making it useful for choosing a consistent palette for a plot or data application.


Discover more about interactive widgets in the Panel interactivity guides, or learn about callbacks and links and declarative UIs with Param.




Parameters#


For details on other options for customizing the component, see the Panel Material UI customization guides.




Core#


    

  • options (dict): A dictionary mapping palette names to lists of colors. The colors can be CSS color strings such as hexadecimal values.
    • 

  • value (object): The currently selected palette as its list of colors.
    • 

  • value_name (str): The name of the currently selected palette. Setting this parameter selects the corresponding option.
    • 

  • ncols (int): The number of columns used to lay out swatches in each palette.
    • 

  • swatch_height (int): The height of each color swatch in pixels.
    • 

  • swatch_width (int): The width of each color swatch in pixels.
    • 







Display#


    

  • disabled (bool): Whether the widget is interactive.
    • 

  • error_state (bool): Whether to display the widget in an error state.
    • 

  • helper_text (str): Text displayed below the widget.
    • 

  • label (str): The title displayed for the widget.
    • 

  • description (str): Tooltip text displayed when hovering over the widget.
    • 







Styling#


    

  • sx (dict): Component-level styling API for fine-grained customization.
    • 

  • theme_config (dict): Theming API for consistent design system integration.
    • 









Basic Usage#


Pass a dictionary of named palettes to options. Each palette is rendered as a visible gradient in the menu:


palettes = {
    "Sunset": ["#fff7bc", "#fec44f", "#d95f0e", "#993404"],
    "Ocean": ["#f7fbff", "#6baed6", "#2171b5", "#08306b"],
    "Forest": ["#f7fcf5", "#74c476", "#238b45", "#00441b"],
}

color_map = pmui.ColorMap(label="Palette", options=palettes, value_name="Ocean")
color_map







            
            
The selected palette is available through both value_name and value:


color_map.value_name, color_map.value





('Ocean', ['#f7fbff', '#6baed6', '#2171b5', '#08306b'])






Swatch Layout and Sizing#


Use ncols to arrange the colors in multiple columns. swatch_width and swatch_height control the size of each color swatch:


pmui.ColorMap(
    label="Large swatches",
    options=palettes,
    value_name="Sunset",
    ncols=2,
    swatch_width=140,
    swatch_height=28
)







            
            




Value and Value Name#


value_name is convenient when working with named palettes, while value exposes the actual list of colors. Updating either representation keeps the other in sync:


color_map.value_name = "Forest"
color_map.value





['#f7fcf5', '#74c476', '#238b45', '#00441b']


color_map.value = palettes["Sunset"]
color_map.value_name





Sunset






Disabled, Error, Helper Text, and Description#


disabled prevents selection. Use error_state and helper_text to communicate validation state, and description to provide additional context in a tooltip:


pmui.Column(
    pmui.ColorMap(
        label="Required palette",
        options=palettes,
        value_name="Ocean",
        error_state=True,
        helper_text="Select a palette before continuing.",
        description="The palette used for the data visualization.",
    ),
    pmui.ColorMap(label="Read-only palette", options=palettes, value_name="Forest", disabled=True),
)







            
            




Example: Reactive Palette Preview#


The selected palette can drive other components with pn.bind. This small example displays the selected palette as a deterministic HTML gradient and reports its name:


def palette_preview(name):
    colors = palettes.get(name, [])
    gradient = ", ".join(colors)
    return pn.pane.HTML(
        f"<div style='height:48px;border-radius:4px;background:linear-gradient(90deg, {gradient})'></div>"
        f"<p>Selected palette: <b>{name}</b></p>"
    )

preview = pn.bind(palette_preview, color_map.param.value_name)
pmui.Column(color_map, preview)







            
            




API Reference#


Show all parameters and their current values:


pmui.ColorMap(label="Palette", options=palettes).api(jslink=True)







            
            




References#





Download this notebook from GitHub (right-click to download).