Merge pull request #3666 from plotly/legend-example

Legend example for `groupclick`

Author: nicolaskruchten

Diff for: doc/python/legend.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.4.2
+      format_version: '1.3'
+      jupytext_version: 1.13.7
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.7
+    version: 3.9.0
   plotly:
     description: How to configure and style the legend in Plotly with Python.
     display_as: file_settings
@@ -445,6 +445,60 @@ fig.update_layout(title="Try Clicking on the Legend Items!")
 fig.show()
 ```
 
+#### Group click toggle behavior
+
+You can also define the toggle behavior for when a user clicks an item in a group. Here we set the `groupclick` for the `legend` to `toggleitem`. This toggles the visibility of just the item clicked on by the user. Set to `togglegroup` and it toggles the visibility of all items in the same group as the item clicked on.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+fig.add_trace(go.Scatter(
+    x=[1, 2, 3],
+    y=[2, 1, 3],
+    legendgroup="group",  # this can be any string, not just "group"
+    legendgrouptitle_text="First Group Title",
+    name="first legend group",
+    mode="markers",
+    marker=dict(color="Crimson", size=10)
+))
+
+fig.add_trace(go.Scatter(
+    x=[1, 2, 3],
+    y=[2, 2, 2],
+    legendgroup="group",
+    name="first legend group - average",
+    mode="lines",
+    line=dict(color="Crimson")
+))
+
+fig.add_trace(go.Scatter(
+    x=[1, 2, 3],
+    y=[4, 9, 2],
+    legendgroup="group2",
+    legendgrouptitle_text="Second Group Title",
+    name="second legend group",
+    mode="markers",
+    marker=dict(color="MediumPurple", size=10)
+))
+
+fig.add_trace(go.Scatter(
+    x=[1, 2, 3],
+    y=[5, 5, 5],
+    legendgroup="group2",
+    name="second legend group - average",
+    mode="lines",
+    line=dict(color="MediumPurple")
+))
+
+fig.update_layout(title="Try Clicking on the Legend Items!")
+fig.update_layout(legend=dict(groupclick="toggleitem"))
+
+fig.show()
+
+```
+
 ### Legend items for continuous fields (2D and 3D)
 
 Traces corresponding to 2D fields (e.g. `go.Heatmap`, `go.Histogram2d`) or 3D fields (e.g. `go.Isosurface`, `go.Volume`, `go.Cone`) can also appear in the legend. They come with legend icons corresponding to each trace type, which are colored using the same colorscale as the trace.