From 1c1fea2eaca7dcc96703289f855ee51bc5fc737c Mon Sep 17 00:00:00 2001
From: Kkkakania <200867803+Kkkakania@users.noreply.github.com>
Date: Tue, 14 Jul 2026 11:12:39 +0800
Subject: [PATCH] Document generated widget options

---
 doc/ref/plotting_options/size_layout.ipynb | 55 +++++++++++++++++++++-
 hvplot/converter.py                        | 16 +++++--
 2 files changed, 67 insertions(+), 4 deletions(-)

diff --git a/doc/ref/plotting_options/size_layout.ipynb b/doc/ref/plotting_options/size_layout.ipynb
index 393b40c1b..ce885e2c1 100644
--- a/doc/ref/plotting_options/size_layout.ipynb
+++ b/doc/ref/plotting_options/size_layout.ipynb
@@ -362,7 +362,7 @@
     "(option-widget_location)=\n",
     "## `widget_location`\n",
     "\n",
-    "Control where widgets appear. Valid values are `'right'` (default), `'left'`, `'bottom'`, `'right'`, `'top'`, `'top_left'`, `'top_right'`, `'bottom_left'`, `'bottom_right'`, `'left_top'`, `'left_bottom'`, `'right_top'`, `'right_bottom'`.\n",
+    "Control where widgets appear. Valid values are `'right_top'` (default), `'left'`, `'bottom'`, `'right'`, `'top'`, `'top_left'`, `'top_right'`, `'bottom_left'`, `'bottom_right'`, `'left_top'`, `'left_bottom'`, `'right_top'`, `'right_bottom'`.\n",
     "\n",
     ":::{important}\n",
     "When this option is set the object returned is no longer a HoloViews object but a Panel layout. In the future we intend to address that, follow [this issue](https://github.com/holoviz/holoviews/issues/6590) for more information.\n",
@@ -404,6 +404,59 @@
     ")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "74bd136d-9cde-4cfb-9fbb-1c7f99c1dfb1",
+   "metadata": {},
+   "source": [
+    "(option-widgets)=\n",
+    "(option-widget_layout)=\n",
+    "(option-widget_type)=\n",
+    "## Customizing generated widgets\n",
+    "\n",
+    "Use `widgets` to map a `groupby` dimension to a Panel widget type or instance. The `widget_layout` option accepts a Panel layout type, such as `pn.Row` or `pn.Column`, and controls how multiple widgets are arranged. Set `widget_type='scrubber'` to replace the individual controls with one player that steps through every combination of grouped values.\n",
+    "\n",
+    "These options return a Panel layout rather than the underlying HoloViews object. A scrubber requires every grouped dimension to define a finite set of values."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0d95aa14-40b4-4ec4-8b60-0a6e3f2ea907",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import panel as pn\n",
+    "import hvplot.pandas  # noqa\n",
+    "\n",
+    "df = hvplot.sampledata.penguins(\"pandas\")\n",
+    "\n",
+    "df.hvplot.scatter(\n",
+    "    x='bill_length_mm', y='bill_depth_mm', frame_width=250,\n",
+    "    groupby='species',\n",
+    "    widgets={'species': pn.widgets.RadioButtonGroup},\n",
+    "    widget_layout=pn.Row, widget_location='top',\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "97eb2f9a-1250-4d4b-94b7-84d8da385924",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import hvplot.pandas  # noqa\n",
+    "\n",
+    "df = hvplot.sampledata.penguins(\"pandas\")\n",
+    "\n",
+    "df.hvplot.scatter(\n",
+    "    x='bill_length_mm', y='bill_depth_mm', frame_width=250,\n",
+    "    groupby=['species', 'island'],\n",
+    "    widget_type='scrubber', widget_location='bottom',\n",
+    ")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "9a7924e9-b9f9-4238-a4cf-e8449cedb8cb",
diff --git a/hvplot/converter.py b/hvplot/converter.py
index f6918b7a6..f537cd405 100644
--- a/hvplot/converter.py
+++ b/hvplot/converter.py
@@ -275,13 +275,23 @@ class HoloViewsConverter:
         width and height or width and aspect are set the plot is set
         to a fixed size, ignoring any responsive option. Only supported by the
         interactive plotting backends.
-    widget_location : str, optional
+    widget_location : str, default='right_top'
         Specifies where to place widgets generated by options like ``groupby``.
-        Valid values are: ``'right'`` (default), ``'left'``, ``'bottom'``,
-        ``'right'``, ``'top'``, ``'top_left'``, ``'top_right'``,
+        Valid values are: ``'left'``, ``'bottom'``, ``'right'``, ``'top'``,
+        ``'top_left'``, ``'top_right'``,
         ``'bottom_left'``, ``'bottom_right'``, ``'left_top'``,
         ``'left_bottom'``, ``'right_top'``, ``'right_bottom'``.
         Only applies if the plot generates widgets (e.g. via ``groupby``).
+    widget_layout : type, default=panel.WidgetBox
+        Panel layout type used to arrange generated widgets. For example,
+        use ``panel.Row`` to display multiple widgets horizontally.
+    widget_type : {'individual', 'scrubber'}, default='individual'
+        Whether to create one widget per grouped dimension or one scrubber
+        that steps through all combinations. Scrubbers require every grouped
+        dimension to define a finite set of values.
+    widgets : dict, optional
+        Mapping from grouped dimension names to Panel widget types or widget
+        instances, used to override the automatically selected widgets.
 
     Axis Options
     ------------