{ "cells": [ { "cell_type": "code", "execution_count": null, "metadata": { "tags": [] }, "outputs": [], "source": [ "import panel as pn\n", "import panel_material_ui as pmui\n", "\n", "pn.extension()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "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.\n", "\n", "Discover more about interactive widgets in the [Panel interactivity guides](https://panel.holoviz.org/how_to/interactivity/index.html), or learn about [callbacks and links](https://panel.holoviz.org/how_to/links/index.html) and [declarative UIs with Param](https://panel.holoviz.org/how_to/param/index.html).\n", "\n", "#### Parameters\n", "\n", "For details on other options for customizing the component, see the [Panel Material UI customization guides](https://panel-material-ui.holoviz.org/customization/index.html).\n", "\n", "##### Core\n", "\n", "* **`options`** (dict): A dictionary mapping palette names to lists of colors. The colors can be CSS color strings such as hexadecimal values.\n", "* **`value`** (object): The currently selected palette as its list of colors.\n", "* **`value_name`** (str): The name of the currently selected palette. Setting this parameter selects the corresponding option.\n", "* **`ncols`** (int): The number of columns used to lay out swatches in each palette.\n", "* **`swatch_height`** (int): The height of each color swatch in pixels.\n", "* **`swatch_width`** (int): The width of each color swatch in pixels.\n", "\n", "##### Display\n", "\n", "* **`disabled`** (bool): Whether the widget is interactive.\n", "* **`error_state`** (bool): Whether to display the widget in an error state.\n", "* **`helper_text`** (str): Text displayed below the widget.\n", "* **`label`** (str): The title displayed for the widget.\n", "* **`description`** (str): Tooltip text displayed when hovering over the widget.\n", "\n", "##### Styling\n", "\n", "* **`sx`** (dict): Component-level styling API for fine-grained customization.\n", "* **`theme_config`** (dict): Theming API for consistent design system integration." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Basic Usage\n", "\n", "Pass a dictionary of named palettes to `options`. Each palette is rendered as a visible gradient in the menu:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [] }, "outputs": [], "source": [ "palettes = {\n", " \"Sunset\": [\"#fff7bc\", \"#fec44f\", \"#d95f0e\", \"#993404\"],\n", " \"Ocean\": [\"#f7fbff\", \"#6baed6\", \"#2171b5\", \"#08306b\"],\n", " \"Forest\": [\"#f7fcf5\", \"#74c476\", \"#238b45\", \"#00441b\"],\n", "}\n", "\n", "color_map = pmui.ColorMap(label=\"Palette\", options=palettes, value_name=\"Ocean\", height=200)\n", "color_map" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The selected palette is available through both `value_name` and `value`:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [] }, "outputs": [], "source": [ "color_map.value_name, color_map.value" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Swatch Layout and Sizing\n", "\n", "Use `ncols` to arrange the colors in multiple columns. `swatch_width` and `swatch_height` control the size of each color swatch:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [] }, "outputs": [], "source": [ "pmui.ColorMap(\n", " label=\"Large swatches\",\n", " options=palettes,\n", " value_name=\"Sunset\",\n", " ncols=2,\n", " swatch_width=140,\n", " swatch_height=28,\n", " height=250\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Value and Value Name\n", "\n", "`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:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [] }, "outputs": [], "source": [ "color_map.value_name = \"Forest\"\n", "color_map.value" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [] }, "outputs": [], "source": [ "color_map.value = palettes[\"Sunset\"]\n", "color_map.value_name" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Disabled, Error, Helper Text, and Description\n", "\n", "`disabled` prevents selection. Use `error_state` and `helper_text` to communicate validation state, and `description` to provide additional context in a tooltip:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [] }, "outputs": [], "source": [ "pmui.Column(\n", " pmui.ColorMap(\n", " label=\"Required palette\",\n", " options=palettes,\n", " value_name=\"Ocean\",\n", " error_state=True,\n", " helper_text=\"Select a palette before continuing.\",\n", " description=\"The palette used for the data visualization.\",\n", " ),\n", " pmui.ColorMap(label=\"Read-only palette\", options=palettes, value_name=\"Forest\", disabled=True),\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Example: Reactive Palette Preview\n", "\n", "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:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [] }, "outputs": [], "source": [ "def palette_preview(name):\n", " colors = palettes.get(name, [])\n", " gradient = \", \".join(colors)\n", " return pn.pane.HTML(\n", " f\"
\"\n", " f\"

Selected palette: {name}

\"\n", " )\n", "\n", "preview = pn.bind(palette_preview, color_map.param.value_name)\n", "pmui.Column(color_map, preview)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### API Reference\n", "\n", "Show all parameters and their current values:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [] }, "outputs": [], "source": [ "pmui.ColorMap(label=\"Palette\", options=palettes).api(jslink=True)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### References\n", "\n", "* [Panel ColorMap documentation](https://panel.holoviz.org/reference/widgets/ColorMap.html)\n", "* [Panel interactivity guides](https://panel.holoviz.org/how_to/interactivity/index.html)\n", "* [Panel Material UI customization guides](https://panel-material-ui.holoviz.org/customization/index.html)" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.14.4" } }, "nbformat": 4, "nbformat_minor": 4 }