{ "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 `Toggle` widget allows users to toggle between `True` and `False` states using a button-style interface. This widget provides the same functionality as the `Checkbox` and `Switch` widgets but with a more prominent visual appearance that's perfect for actions and feature toggles.\n", "\n", "Ideal for primary actions, feature toggles, and situations where you want the toggle state to be highly visible and engaging, the `Toggle` widget offers a button-like alternative to traditional checkboxes and switches.\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", "* **`disabled`** (bool): When True, the widget becomes non-interactive and appears grayed out.\n", "* **`value`** (bool): The current state of the toggle (`True` for pressed/active, `False` for unpressed/inactive).\n", "\n", "##### Display\n", "\n", "* **`end_icon`** (str): An icon displayed to the right of the button label. Accepts Material UI icon names or SVG strings.\n", "* **`icon`** (str): An icon displayed to the left of the button label. Accepts Material UI icon names or SVG strings.\n", "* **`icon_size`** (str): The size of the icons (e.g., '12px', '1em', '2rem').\n", "* **`label`** (str): The descriptive text displayed on the toggle button.\n", "* **`variant`** (str): The visual style of the button - `'contained'`, `'outlined'`, or `'text'`.\n", "\n", "##### Styling\n", "\n", "- **`color`** (str): The color theme applied to the toggle button when active.\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", "- **`button_style`**: Alias for `variant`\n", "- **`button_type`**: Alias for `color`\n", "- **`name`**: Alternative parameter name for `label`\n", "\n", "___" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Basic Usage\n", "\n", "Getting started with the Toggle widget is straightforward. Here's how to create a simple toggle button with a descriptive label and initial state:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "toggle = pmui.Toggle(label='Toggle', button_type='success', value=True)\n", "\n", "toggle" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `value` parameter automatically updates to reflect the toggle state: `True` when pressed/active, `False` when unpressed/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": [ "### Color Options\n", "\n", "Customize your toggle'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.Toggle(label=\"secondary\", color=\"secondary\", 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.Toggle(label=color, color=color, value=True) for color in pmui.Toggle.param.color.objects)\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Icons and Visual Enhancement\n", "\n", "The `Toggle` widget supports various ways to add visual elements. You can use Unicode characters and emoji in the label for simple graphical buttons:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.FlexBox(\n", " pmui.Toggle(label='\\u25c0', width=50),\n", " pmui.Toggle(label='\\u25b6', width=50),\n", " pmui.Toggle(label='πŸ”', width=100),\n", " pmui.Toggle(label=\"▢️ Play\", width=100),\n", " pmui.Toggle(label=\"Pause ⏸️\", width=100)\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "For more professional interfaces, you can use explicit icons. Material UI provides a comprehensive icon library accessible by name:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.Toggle(icon='lock', button_type='light', icon_size='2em')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You can also use custom SVG icons for complete design control:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "shuffle_icon = \"\"\"\n", "\n", " \n", " \n", " \n", " \n", " \n", "\n", "\"\"\"\n", "\n", "pmui.Toggle(icon=shuffle_icon, button_type='success', label='Shuffle', icon_size='2em')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "For enhanced visual communication, combine both start and end icons:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.Toggle(icon='send', button_type='light', icon_size='2em', end_icon='rocket', label='Sent')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Disabled and Loading States\n", "\n", "Like other widgets, the `Toggle` can be disabled and/or show a loading indicator to provide clear feedback during various application states:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.Toggle(label=\"Toggle\", disabled=True, loading=True)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Example: Notification Toggle\n", "\n", "Let's create a practical example that demonstrates how toggles work in real applications. This notification 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", "notifications_toggle = pmui.Toggle(\n", " label=\"Notifications\", \n", " icon=\"notifications\", \n", " color=\"primary\",\n", " value=True\n", ")\n", "\n", "def create_notification_status(value):\n", " if value:\n", " return \"πŸ”” Notifications are enabled - you'll receive updates\"\n", " \n", " return \"πŸ”• Notifications are disabled - you won't receive updates\"\n", "\n", "notification_status = pn.bind(create_notification_status, notifications_toggle)\n", "\n", "pmui.Column(notifications_toggle, notification_status)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### API Reference\n", "\n", "#### Interactive Parameter Explorer\n", "\n", "The `Toggle` 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.Toggle(label=\"Toggle\").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 UI Toggle Button:**\n", "\n", "- [Material UI Toggle Button Reference](https://mui.com/material-ui/react-toggle-button/) - Comprehensive documentation for the underlying Material UI component\n", "- [Material UI Toggle Button API](https://mui.com/material-ui/api/toggle-button/) - Complete API reference with advanced configuration options and examples" ] } ], "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.9" } }, "nbformat": 4, "nbformat_minor": 4 }