{ "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": [ "Floating Action Buttons or `Fab`s for short allow users to take actions, and make choices, with a single click or tap. In contrast to the `Button` the `Fab` is designed performs the primary, or most common, action on a screen.\n", "\n", "In addition to a `value` parameter, which will toggle from `False` to `True` while the click event is being processed, an additional `clicks` parameter is available, that can be watched to subscribe to click events.\n", "\n", "Buttons communicate actions that users can take. They are typically placed throughout your UI, in places like\n", "\n", "- Modal windows\n", "- Forms\n", "- Cards\n", "- Toolbars\n", "\n", "Discover more on using widgets to add interactivity to your applications in the [how-to guides on interactivity](https://panel.holoviz.org/how_to/interactivity/index.html). Alternatively, learn [how to set up callbacks and (JS-)links between parameters](https://panel.holoviz.org/how_to/links/index.html) or [how to use them as part of 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 [customization guides](https://panel-material-ui.holoviz.org/customization/index.html).\n", "\n", "##### Core\n", "\n", "* **`clicks`** (int): Number of clicks (can be listened to)\n", "* **`disabled`** (boolean): Whether the widget is editable.\n", "* **`href`** (str): The link to navigate to when clicking the button.\n", "* **`value`** (boolean): Toggles from `False` to `True` while the event is being processed.\n", "\n", "##### Display\n", "\n", "* **`color`** (str): The color variant of the button, which must be one of `'default'` (white), `'primary'` (blue), `'success'` (green), `'info'` (yellow), `'light'` (light), or `'danger'` (red).\n", "* **`description`** (str | Bokeh Tooltip | pn.widgets.TooltipIcon): A description which is shown when the widget is hovered.\n", "* **`icon`** (str): An icon to render to the left of the button label. Either an SVG or an icon name which is loaded from [Material UI Icons](https://mui.com/material-ui/material-icons).\n", "* **`icon_size`** (str): Size of the icon as a string, e.g. 12px or 1em.\n", "* **`label`** (str): The title of the widget.\n", "* **`variant`** (str): The button style, either 'circular' or 'extended'.\n", "\n", "##### Styling\n", "\n", "- **`sx`** (dict): Component level styling API.\n", "- **`theme_config`** (dict): Theming API.\n", "\n", "##### Aliases\n", "\n", "For compatibility with Panel certain parameters are allowed as aliases:\n", "\n", "- **`button_style`**: Alias for `variant`\n", "- **`button_type`**: Alias for `color`\n", "- **`name`**: Alias for `label`\n", "\n", "#### Methods\n", "\n", "- **`on_click`**: Registers a callback to be executed when the `Fab` is clicked.\n", "- **`js_on_click`**: Allows registering a Javascript callback to be executed when the `Fab` is clicked.\n", "- **`jscallback`**: Allows registering a Javascript callback to be executed when a property changes on the `Fab`.\n", "\n", "##### Callback Arguments\n", "\n", "- **`on_click`** (callable): A function taking an `event` argument. Executed when the `Fab` is clicked.\n", "- **`js_on_click`** (str): A string containing the Javascript code. Executed run when the `Fab` is clicked.\n", "\n", "___" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Basic Usage\n", "\n", "The `Fab` button is designed as way to invoke the most common action in the app:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "fab = pmui.Fab(color='primary', label='Click me')\n", "\n", "fab" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `clicks` parameter will report the number of times the button has been pressed:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "fab.clicks" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "While the `value` parameter toggles to `True` while the click event is processed:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "fab.value" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Link Button\n", "\n", "A `Fab` can also have an `href` parameter which will cause it to navigate to the provided link on click:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.Fab(href=\"https://panel.holoviz.org\", label=\"Open Panel docs\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You may additionally specify where to open the link via the `target` parameter:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.Fab(href=\"https://panel.holoviz.org\", label=\"Open Panel docs in new window or tab\", target=\"_blank\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Handling Clicks\n", "\n", "You can `bind` to the `Fab` to trigger actions when the `Fab` is clicked." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "toggle_button = pmui.Fab(label=\"Start Spinning\")\n", "indicator = pmui.LoadingSpinner(value=False, size=25)\n", "\n", "def update_indicator(event):\n", " indicator.value = not indicator.value\n", " toggle_button.label=\"Stop Spinning\" if indicator.value else \"Start Spinning\"\n", "\n", "pn.bind(update_indicator, toggle_button, watch=True)\n", "\n", "pmui.Row(toggle_button, indicator)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Alternatively you can use the ``on_click`` method to trigger a function when the button is clicked:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "click_button = pmui.Fab(label=\"Increment\", align=\"center\")\n", "text = pmui.TextInput(value='Clicked 0 times', disabled=True)\n", "\n", "def handle_click(event):\n", " text.value = 'Clicked {0} times'.format(click_button.clicks)\n", "\n", "click_button.on_click(handle_click)\n", " \n", "pmui.Row(click_button, text)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Disabled and Loading\n", "\n", "Like any other widget the `Button` can be `disabled` and / or set to `loading`:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.Fab(label=\"Loading\", disabled=True, loading=True, color=\"primary\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Positioning\n", "\n", "A floating action button generally should use 'fixed', 'absolute' or 'sticky' positioning. To achieve this you can set the `styles` attribute:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "position = {\n", " \"position\": \"absolute\",\n", " \"bottom\": \"0\",\n", "}\n", "\n", "pmui.Column(\n", " pmui.Fab(color='default', styles=dict(position='absolute')),\n", " pmui.Fab(color='primary', styles=dict(position='absolute', right=\"0\")),\n", " pmui.Fab(color='secondary', styles=dict(position=\"absolute\", bottom=\"0\")),\n", " pmui.Fab(color='error', styles=dict(position=\"absolute\", bottom=\"0\", right=\"0\")),\n", " height=200, sizing_mode='stretch_width'\n", ").show()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To position it on a scrollable container use `'sticky'`:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "sticky_fab = pmui.Fab(color='primary', styles={'position': 'sticky', 'left': '100%', 'bottom': '12px'})\n", "\n", "pn.Column(\n", " *range(100),\n", " sticky_fab,\n", " scroll='y',\n", " width=200,\n", " height=300\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "and to absolutely position it on the page use `'fixed'`." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Color and Variant\n", "\n", "The color of the button can be set by selecting one of the available `color` values and the `variant` can be `'circular'` or `'extended'`:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.Row(\n", " *(pmui.Column(*(pmui.Fab(label=f'{color=}, {variant=}', color=color, variant=variant)\n", " for color in pmui.Fab.param.color.objects))\n", " for variant in pmui.Fab.param.variant.objects)\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Icons" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "By default the circular variant will pnly display an `icon`, which can be defined as an icon loaded from [Material Icons](https://fonts.google.com/icons?icon.set=Material+Icons):" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.Row(\n", " pmui.Fab(icon='warning', color='warning', label='WARNING'),\n", " pmui.Fab(icon='bug_report', color='error', label='ERROR')\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "or as an explicit SVG:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cash_icon = \"\"\"\n", "\n", " \n", " \n", " \n", " \n", "\n", "\"\"\"\n", "\n", "pmui.Fab(icon=cash_icon, color='success', label='Checkout', icon_size='2em', variant='extended')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You can also provide an end icon:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.Fab(label=\"Send\", end_icon=\"send_icon\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Example: Random Quotes" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import panel as pn\n", "import panel_material_ui as pmui\n", "import time\n", "import random\n", "\n", "pn.extension()\n", "\n", "submit = pmui.Fab(label=\"Update Quote\", variant=\"extended\", color=\"primary\", size=\"small\", icon=\"refresh\",)\n", "\n", "motivational_quotes = [\n", " \"🚀 The best time to plant a tree was 20 years ago. The second best time is now!\",\n", " \"💪 Success is not final, failure is not fatal: it is the courage to continue that counts.\",\n", " \"🌟 The only way to do great work is to love what you do.\",\n", " \"⚡ Innovation distinguishes between a leader and a follower.\",\n", " \"🎯 The future belongs to those who believe in the beauty of their dreams.\",\n", " \"🔥 Don't watch the clock; do what it does. Keep going!\",\n", " \"✨ Your limitation—it's only your imagination.\",\n", "]\n", "\n", "def pick_quote(value):\n", " yield \"Loading Quote...\"\n", " time.sleep(0.5)\n", " yield random.choice(motivational_quotes)\n", "\n", "quote = pn.bind(pick_quote, submit)\n", "\n", "pmui.Column(quote, submit)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Example: Random Quotes (Javascript)\n", "\n", "When you click the button an alert will open and display a quote:" ] }, { "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", "javascript_code = \"\"\"\n", "const quotes = [\n", " \"🚀 The best time to plant a tree was 20 years ago. The second best time is now!\",\n", " \"💪 Success is not final, failure is not fatal: it is the courage to continue that counts.\",\n", " \"🌟 The only way to do great work is to love what you do.\",\n", " \"⚡ Innovation distinguishes between a leader and a follower.\",\n", " \"🎯 The future belongs to those who believe in the beauty of their dreams.\",\n", " \"🔥 Don't watch the clock; do what it does. Keep going!\",\n", " \"✨ Your limitation—it's only your imagination.\"\n", "];\n", "const randomQuote = quotes[Math.floor(Math.random() * quotes.length)];\n", "alert(randomQuote);\n", "\"\"\"\n", "\n", "pmui.Fab(label=\"Show Quote\", color=\"primary\", size=\"small\", icon=\"refresh\", js_on_click=javascript_code)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### API Reference\n", "\n", "#### Parameters" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pmui.Fab(label=\"Click Me\").api(jslink=True)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### References\n", "\n", "**Panel Documentation:**\n", "\n", "- [How-to guides on interactivity](https://panel.holoviz.org/how_to/interactivity/index.html) - Learn how to add interactivity to your applications using widgets\n", "- [Setting up callbacks and links](https://panel.holoviz.org/how_to/links/index.html) - Connect parameters between components and create reactive interfaces\n", "- [Declarative UIs with Param](https://panel.holoviz.org/how_to/param/index.html) - Build parameter-driven applications\n", "\n", "**Material UI Fab:**\n", "\n", "- [Material UI Fab Reference](https://mui.com/material-ui/react-fab/) - Complete documentation for the underlying Material UI component\n", "- [Material UI Fab API](https://mui.com/material-ui/api/fab/) - Detailed API reference and configuration options" ] } ], "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 }