{
 "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 `MultiSelect` widget allows selecting multiple values from a list of options. It is built upon the [Material UI Select](https://mui.com/material-ui/react-select/#multiple-select) component with the `native` and `multiple` props.\n",
    "\n",
    "The `MultiSelect` widget falls into the broad category of multi-value, option-selection widgets that provide a compatible API and include the [`CrossSelector`](CrossSelector.ipynb), [`CheckBoxGroup`](CheckBoxGroup.ipynb) and [`CheckButtonGroup`](CheckButtonGroup.ipynb) widgets.\n",
    "\n",
    "Explore more about using widgets to add interactivity to your applications in the [Make your component interactive](https://panel.holoviz.org/how_to/interactivity/index.html), [Link Parameters](https://panel.holoviz.org/how_to/links/index.html) or [Declarative API](https://panel.holoviz.org/how_to/param/index.html) guides.\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",
    "* **`disabled`** (boolean): Whether the widget is editable.\n",
    "* **`max_items`** (int): Maximum number of options that can be selected.\n",
    "* **`options`** (list or dict): A list or dictionary of options to select from.\n",
    "* **`size`** (int): The number of options to display at once. Controls the visible height of the list area.\n",
    "* **`value`** (list): Currently selected option values.\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`color`** (str): The color variant of the input.\n",
    "* **`error_state`** (boolean): Whether to display in error state.\n",
    "* **`helper_text`** (str): Helper text displayed below the input field.\n",
    "* **`label`** (str): The title of the widget.\n",
    "* **`variant`** (str): One of `'filled'`, `'outlined'` (default), or `'standard'`.\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",
    "- **`name`**: Alias for `label`.\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Basic Usage\n",
    "\n",
    "The `MultiSelect` widget allows selecting multiple values from a list of `options`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "multi_select = pmui.MultiSelect(\n",
    "    label='Fruits', value=['Apple', 'Pear'],\n",
    "    options=['Apple', 'Banana', 'Pear', 'Strawberry'], size=4\n",
    ")\n",
    "\n",
    "multi_select"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Like most other widgets, `MultiSelect` has a value parameter that can be accessed or set:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "multi_select.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `options` parameter also accepts a dictionary whose keys are going to be the visible labels:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dict_select = pmui.MultiSelect(\n",
    "    label='Frameworks', value=['panel', 'bokeh'],\n",
    "    options={'Panel': 'panel', 'Bokeh': 'bokeh', 'Plotly': 'plotly', 'Matplotlib': 'matplotlib'},\n",
    "    size=4\n",
    ")\n",
    "\n",
    "dict_select"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Filled and Standard Variants"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "options = ['Apple', 'Banana', 'Pear', 'Strawberry']\n",
    "\n",
    "pmui.Row(\n",
    "    pmui.MultiSelect(label='Outlined', options=options, variant=\"outlined\", size=4, width=200),\n",
    "    pmui.MultiSelect(label='Filled', options=options, variant=\"filled\", size=4, width=200),\n",
    "    pmui.MultiSelect(label='Standard', options=options, variant=\"standard\", size=4, width=200),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Colors"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pn.FlexBox(*[\n",
    "    pmui.MultiSelect(label=color, options=['A', 'B', 'C'], color=color, value=['A'], size=3, width=150)\n",
    "    for color in pmui.MultiSelect.param.color.objects\n",
    "])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Size\n",
    "\n",
    "The `size` parameter controls how many rows are visible at once."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "many_options = [f\"Option {i}\" for i in range(20)]\n",
    "\n",
    "pmui.Row(\n",
    "    pmui.MultiSelect(label='size=5', options=many_options, size=5, width=200),\n",
    "    pmui.MultiSelect(label='size=12', options=many_options, size=12, width=200),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Max Items\n",
    "\n",
    "The `max_items` parameter limits how many options can be selected at once. When the limit is reached, selecting a new option deselects the oldest one:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.MultiSelect(\n",
    "    label='Select up to 3',\n",
    "    options=['Apple', 'Banana', 'Pear', 'Strawberry', 'Mango', 'Kiwi'],\n",
    "    max_items=3, size=6\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Helper Text\n",
    "\n",
    "The `helper_text` parameter displays additional guidance text below the input field:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.MultiSelect(label='Fruits', options=['Apple', 'Banana', 'Pear'], value=[], helper_text='Hold Ctrl to select multiple')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Disabled"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.MultiSelect(\n",
    "    label='Disabled', options=['Apple', 'Banana', 'Pear'],\n",
    "    value=['Apple'], disabled=True, size=3\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Icon Labels\n",
    "\n",
    "Material icon tokens like `:material/zoom_out_map:` render as icons in labels and option labels."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.MultiSelect(\n",
    "    label=\"Modes :material/zoom_out_map:\",\n",
    "    options={\"Zoom :material/zoom_out_map:\": \"zoom\", \"Explore :material/explore:\": \"explore\"},\n",
    "    value=[\"zoom\"],\n",
    "    size=2,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### API Reference\n",
    "\n",
    "#### Parameters\n",
    "\n",
    "The `MultiSelect` widget exposes a number of options which can be changed from both Python and Javascript. Try out the effect of these parameters interactively:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.MultiSelect(\n",
    "    label='Fruits', options=['Apple', 'Banana', 'Pear', 'Strawberry', 'Mango', 'Kiwi'],\n",
    "    value=['Apple'], size=6\n",
    ").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 Select:**\n",
    "\n",
    "- [Material UI Select Reference](https://mui.com/material-ui/react-select/#multiple-select) - Complete documentation for the underlying Material UI component\n",
    "- [Material UI Select API](https://mui.com/material-ui/api/select/) - 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.14.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}