feat(pie): document new properties for controlling the activeId

plouc · Nov 19, 2023 · fcc4979 · fcc4979
1 parent c87658e
commit fcc4979
Show file tree

Hide file tree

Showing 2 changed files with 56 additions and 0 deletions.
diff --git a/website/src/data/components/pie/meta.yml b/website/src/data/components/pie/meta.yml
@@ -17,6 +17,8 @@ Pie:
       link: pie--adding-a-metric-in-the-center-using-a-custom-layer
     - label: Custom arc label component
       link: pie--custom-arc-label-component
+    - label: Sync activeId between two pies
+      link: pie--controlled-active-id
   description: |
     Generates a pie chart from an array of data, each datum must have an
     id and a value property.

diff --git a/website/src/data/components/pie/props.ts b/website/src/data/components/pie/props.ts
@@ -508,6 +508,60 @@ const props: ChartProperty[] = [
             max: 50,
         },
     },
+    {
+        key: 'activeId',
+        flavors: ['svg'],
+        help: `Programmatically control the \`activeId\`.`,
+        description: `
+            This property should be used with \`onActiveIdChange\`,
+            allowing you to fully control which arc should be highlighted.
+            
+            You might want to use this in case:
+            
+            - You want to synchronize the \`activeId\` with other UI elements defined
+              outside of nivo, or other nivo charts.
+            - You're creating some kind of *story-telling* app where you want to highlight
+              certain arcs based on external input.
+            - You want to change the default behavior and highlight arcs depending on clicks
+              rather than \`onMouseEnter\`, which can be desirable on mobile for example.
+        `,
+        type: 'string | number | null',
+        required: false,
+        group: 'Interactivity',
+    },
+    {
+        key: 'onActiveIdChange',
+        flavors: ['svg'],
+        help: `Programmatically control the \`activeId\`.`,
+        description: `
+            This property should be used with \`activeId\`,
+            allowing you to fully control which arc should be highlighted.
+            
+            You might want to use this in case:
+            
+            - You want to synchronize the \`activeId\` with other UI elements defined
+              outside of nivo, or other nivo charts.
+            - You're creating some kind of *story-telling* app where you want to highlight
+              certain arcs based on external input.
+            - You want to change the default behavior and highlight arcs depending on clicks
+              rather than \`onMouseEnter\`, which can be desirable on mobile for example.
+        `,
+        type: 'string | number | null',
+        required: false,
+        group: 'Interactivity',
+    },
+    {
+        key: 'defaultActiveId',
+        flavors: ['svg'],
+        help: `Default \`activeId\`.`,
+        description: `
+            You can use this property in case you want to define a default \`activeId\`,
+            but still don't want to control it by yourself (using \`activeId\` & \`onActiveIdChange\`).
+        `,
+        type: 'string | number | null',
+        required: false,
+        group: 'Interactivity',
+    },
     {
         key: 'onMouseEnter',
         flavors: ['svg'],