{ "cells": [ { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import panel as pn\n", "import panel_material_ui as pmui\n", "\n", "pn.extension()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `ToggleIcon` widget allows users to toggle between `True` and `False` states using a sleek icon-based interface. This widget provides the same functionality as the `Checkbox`, `Switch`, and `Toggle` widgets but with a minimalist visual approach that's perfect for space-conscious designs.\n", "\n", "Ideal for compact interfaces, toolbar buttons, and situations where you need toggle functionality without taking up much visual space, the `ToggleIcon` widget offers an elegant, icon-only alternative to traditional toggle controls.\n", "\n", "#### Parameters\n", "\n", "For more details on customization options, see the [customization guides](https://panel-material-ui.holoviz.org/customization/index.html).\n", "\n", "##### Core\n", "\n", "* **`active_icon`** (str): The icon displayed when the toggle is active. Accepts [Material icon names](https://fonts.google.com/icons) or SVG strings.\n", "* **`disabled`** (bool): When True, the widget becomes non-interactive and appears grayed out.\n", "* **`icon`** (str): The icon displayed when the toggle is inactive. Accepts [Material icon names](https://fonts.google.com/icons) or SVG strings.\n", "* **`value`** (bool): The current state of the toggle (`True` for active, `False` for inactive).\n", "\n", "##### Display\n", "\n", "* **`icon_size`** (`str`): Controls the size of the icon. Usually automatically determined based on the `size` but can be used to control icon size independently.\n", "* **`label`** (str): Optional text label displayed alongside the icon.\n", "* **`size`** (`Literal[\"small\", \"medium\", \"large\"]`): Controls the size of the widget.\n", "\n", "##### Styling\n", "\n", "* **`color`** (str): The color variant of the icon when active, which must be one of `'default'` (white), `'primary'` (blue), `'success'` (green), `'info'` (yellow), `'light'` (light), or `'danger'` (red).\n", "* **`sx`** (dict): Advanced styling options for fine-tuned appearance control.\n", "* **`theme_config`** (dict): Theme-level configuration for consistent styling across your application.\n", "\n", "##### Aliases\n", "\n", "For seamless compatibility with Panel widgets, certain parameters accept aliases:\n", "\n", "* **`name`**: Alternative parameter name for `label`\n", "\n", "___" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Basic Usage\n", "\n", "Getting started with the ToggleIcon widget is straightforward. Here's how to create a simple toggle icon that changes between two different states:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "toggle = pmui.ToggleIcon(icon=\"add_box\")\n", "\n", "toggle" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "By default, when `value` is `True`, the `active_icon` is displayed. If no `active_icon` is specified, Material Icons will automatically use the filled version of the icon when available.\n", "\n", "The `value` parameter automatically updates to reflect the toggle state: `True` when active, `False` when inactive. You can also programmatically set this value to control the toggle state:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "toggle.value" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You can also add a text label alongside the icon using the `label` parameter for better accessibility and context:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.ToggleIcon(icon=\"favorite\", active_icon=\"check\", label=\"Favorite\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Using Material Icons\n", "\n", "The `ToggleIcon` widget uses [Google's Material Icons](https://fonts.google.com/icons), which provide a consistent, beautiful set of icons following Material Design principles. Icon names use underscores instead of dashes (e.g., `favorite_border`, `thumb_up`, `check_circle`).\n", "\n", "Popular icon pairs for toggles include:\n", "- `favorite_border` / `favorite` (for favorites/likes)\n", "- `bookmark_border` / `bookmark` (for bookmarks)\n", "- `visibility_off` / `visibility` (for show/hide)\n", "- `thumb_down` / `thumb_up` (for reactions)\n", "\n", "___" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.FlexBox(\n", " pmui.ToggleIcon(icon=\"favorite_border\", active_icon=\"favorite\", label=\"Favorite\"),\n", " pmui.ToggleIcon(icon=\"bookmark_border\", active_icon=\"bookmark\", label=\"Bookmark\"),\n", " pmui.ToggleIcon(icon=\"visibility_off\", active_icon=\"visibility\", label=\"Show/Hide\"),\n", " pmui.ToggleIcon(icon=\"thumb_down\", active_icon=\"thumb_up\", label=\"Like/Dislike\")\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Icon Customization\n", "\n", "The ToggleIcon widget offers intelligent icon selection. When only an `icon` is provided, Material Icons automatically selects the corresponding filled version for the active state:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.ToggleIcon(icon=\"thumb_down\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You can customize this behavior by explicitly setting both icons to create meaningful visual transitions:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.ToggleIcon(icon=\"thumb_down\", active_icon=\"thumb_up\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The icon will automatically adapt to the specified `width`/`height` but you may also provide an explicit `size`:\n", "\n", "### Size Options\n", "\n", "Choose the appropriate icon size for your interface using the `size` parameter. The icon automatically adapts to your layout, or you can specify explicit sizing:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.ToggleIcon(icon=\"thumb_down\", active_icon=\"thumb_up\", size='small')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You may also independently control the `icon_size`:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.ToggleIcon(icon=\"thumb_down\", active_icon=\"thumb_up\", icon_size='30px')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Color Options\n", "\n", "Customize your toggle icon's appearance to match your application's design language using the `color` parameter. Each color provides different visual emphasis and semantic meaning:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.ToggleIcon(icon=\"favorite_border\", active_icon=\"favorite\", color=\"primary\", value=True)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Here's a showcase of all available color options:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.FlexBox(\n", " *(pmui.ToggleIcon(icon=\"favorite_border\", active_icon=\"favorite\", label=color, color=color, value=True) \n", " for color in pmui.ToggleIcon.param.color.objects)\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Custom SVG Icons\n", "\n", "For complete design control, you can use custom SVG icons instead of the built-in Material icons. This is perfect for brand-specific iconography:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "SVG = \"\"\"\n", "\n", "\"\"\"\n", "ACTIVE_SVG = \"\"\"\n", "\n", "\"\"\"\n", "\n", "pmui.ToggleIcon(icon=SVG, active_icon=ACTIVE_SVG)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Disabled and Loading States\n", "\n", "The `ToggleIcon` widget supports both disabled and loading states to provide clear feedback during various application states. Use these features to guide user interactions effectively:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.ToggleIcon(icon=\"thumb_down\", active_icon=\"thumb_up\", disabled=True, loading=True)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Real-World Example: Favorite Toggle\n", "\n", "Let's create a practical example that demonstrates how toggle icons work in real applications. This favorite toggle shows how to bind toggle values to dynamic content updates:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import panel as pn\n", "import panel_material_ui as pmui\n", "\n", "pn.extension()\n", "\n", "favorite_toggle = pmui.ToggleIcon(\n", " icon=\"favorite\", \n", " active_icon=\"check\",\n", " label=\"Favorite\",\n", " value=False\n", ")\n", "\n", "def create_favorite_status(value):\n", " if value:\n", " return \"👍 Added to favorites!\"\n", " \n", " return \"❤️ Click the heart to add to favorites\"\n", "\n", "favorite_status = pn.bind(create_favorite_status, favorite_toggle)\n", "\n", "pmui.Column(favorite_toggle, favorite_status)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### API Reference\n", "\n", "#### Interactive Parameter Explorer\n", "\n", "The `ToggleIcon` widget offers numerous customization options that can be modified from both Python and JavaScript. Explore these parameters interactively to see their effects in real-time:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.ToggleIcon(icon=\"favorite_border\", active_icon=\"favorite\", label=\"ToggleIcon\").api(jslink=True)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Further Learning\n", "\n", "**Panel Documentation:**\n", "\n", "- [How-to guides on interactivity](https://panel.holoviz.org/how_to/interactivity/index.html) - Master the art of creating interactive applications with widgets and dynamic updates\n", "- [Setting up callbacks and links](https://panel.holoviz.org/how_to/links/index.html) - Connect widget parameters to create responsive, reactive user interfaces\n", "- [Declarative UIs with Param](https://panel.holoviz.org/how_to/param/index.html) - Build sophisticated parameter-driven applications with minimal code\n", "\n", "**Material Icons:**\n", "\n", "- [Material Icons Library](https://fonts.google.com/icons) - Browse the complete collection of beautiful, customizable icons used by the `ToggleIcon` widget" ] } ], "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.12.2" } }, "nbformat": 4, "nbformat_minor": 4 }