> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Action Components

* A customizable button component that can be used to add custom actions and extend the functionality of any Velt component. Some examples include:
  * Add custom filtering, sorting and grouping to the Comment Sidebar
  * Add custom actions to each item in the Notifications panel.
  * Add custom actions to the Comment Dialog.
* In the [callback event](#callback-event), in addition to returning the button context, it also returns the key component data that it sits within Eg: `CommentAnnotation`, `Comment`, `Notification`, `CommentSidebarData` etc.

## Types

* `button`: Basic clickable button
* `button-toggle`: Toggleable button that maintains state
* `single-select`: Single select (radio button) group
* `multi-select`: Multi select (checkbox) group

## Component Props

| Property   | Type    | Required | Description                                                                                                                                                                        |
| ---------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`       | string  | Yes      | Unique identifier for the button. This can be a static id or a dynamic id using a template variable.                                                                               |
| `type`     | string  | No       | Button type: 'button' (default), 'button-toggle', 'multi-select', or 'single-select'                                                                                               |
| `disabled` | boolean | No       | Whether the button is disabled                                                                                                                                                     |
| `active`   | boolean | No       | Whether the button is in active/selected state. Use this if you want to add a default state to the button. Applies to 'button-toggle', 'multi-select', or 'single-select' buttons. |
| `group`    | string  | No       | Group identifier for single-select/multi-select buttons                                                                                                                            |

## Usage

### Button

<Tabs>
  <Tab title="React / Next.js">
    ```jsx {6-8} theme={null}
    <VeltWireframe>
      <VeltCommentsSidebarWireframe.Header>
        <VeltCommentsSidebarWireframe.Search />
        <VeltCommentsSidebarWireframe.FilterButton />

        <VeltButtonWireframe id="close-sidebar" type="button">
            <div className="custom-button">Close Sidebar</div>
        </VeltButtonWireframe>

      </VeltCommentsSidebarWireframe.Header>
    </VeltWireframe>
    ```

    **Handle the button click event:**

    ```jsx theme={null}
    // Hook
    const veltButtonClickEventData = useVeltEventCallback('veltButtonClick');
    useEffect(() => {
      if (veltButtonClickEventData) {
        if (veltButtonClickEventData.buttonContext.clickedButtonId === 'close-sidebar') {
          // Close sidebar
        }
      }
    }, [veltButtonClickEventData]);

    // API Method
    client.on('veltButtonClick').subscribe(veltButtonClickEventData => {
      if (veltButtonClickEventData) {
        if (veltButtonClickEventData.buttonContext.clickedButtonId === 'close-sidebar') {
          // Close sidebar
        }
      }
    });

    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html {6-8} theme={null}
    <velt-wireframe style="display:none;">
      <velt-comments-sidebar-wireframe-header>
        <velt-comments-sidebar-wireframe-search></velt-comments-sidebar-wireframe-search>
        <velt-comments-sidebar-wireframe-filter-button></velt-comments-sidebar-wireframe-filter-button>

        <velt-button-wireframe id="close-sidebar" type="button">
            <div class="custom-button">Close Sidebar</div>
        </velt-button-wireframe>

      </velt-comments-sidebar-wireframe-header>
    </velt-wireframe>
    ```

    **Handle the button click event:**

    ```js theme={null}
    Velt.on('veltButtonClick').subscribe(veltButtonClickEventData => {
      if (veltButtonClickEventData) {
        if (veltButtonClickEventData.buttonContext.clickedButtonId === 'close-sidebar') {
          // Close sidebar
        }
      }
    });

    ```
  </Tab>
</Tabs>

### Button Toggle

<Tabs>
  <Tab title="React / Next.js">
    ```jsx {6-8} theme={null}
    <VeltWireframe>
      <VeltCommentsSidebarWireframe.Header>
        <VeltCommentsSidebarWireframe.Search />
        <VeltCommentsSidebarWireframe.FilterButton />
        {/* Optional: Set the active prop to true if you want to add a default state to the button */}
        <VeltButtonWireframe id="toggleCommentPins" type="button-toggle" active={true}>
            <div className="custom-button">Toggle Comment Pins</div>
        </VeltButtonWireframe>

      </VeltCommentsSidebarWireframe.Header>
    </VeltWireframe>
    ```

    **Handle the button click event:**

    ```jsx theme={null}
    // Hook
    const veltButtonClickEventData = useVeltEventCallback('veltButtonClick');
    useEffect(() => {
      if (veltButtonClickEventData) {
        if (veltButtonClickEventData.buttonContext?.clickedButtonId === 'toggleCommentPins') {
          if (veltButtonClickEventData.buttonContext?.selections?.ungrouped['toggleCommentPins']) {
            commentElement.showCommentsOnDom();
          } else {
            commentElement.hideCommentsOnDom(); 
          }
        }
      }
    }, [veltButtonClickEventData]);

    // API Method
    client.on('veltButtonClick').subscribe(veltButtonClickEventData => {
      if (veltButtonClickEventData) {
        if (veltButtonClickEventData.buttonContext?.clickedButtonId === 'toggleCommentPins') {
          if (veltButtonClickEventData.buttonContext?.selections?.ungrouped['toggleCommentPins']) {
            commentElement.showCommentsOnDom();
          } else {
            commentElement.hideCommentsOnDom(); 
          }
        }
      }
    });
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html {6-8} theme={null}
    <velt-wireframe style="display:none;">
      <velt-comments-sidebar-wireframe-header>
        <velt-comments-sidebar-wireframe-search></velt-comments-sidebar-wireframe-search>
        <velt-comments-sidebar-wireframe-filter-button></velt-comments-sidebar-wireframe-filter-button>

        <!-- Optional: Set the active prop to true if you want to add a default state to the button -->
        <velt-button-wireframe id="toggleCommentPins" type="button-toggle" active="true">
            <div class="custom-button">Toggle Comment Pins</div>
        </velt-button-wireframe>

      </velt-comments-sidebar-wireframe-header>
    </velt-wireframe>
    ```

    **Handle the button click event:**

    ```js theme={null}
    Velt.on('veltButtonClick').subscribe(veltButtonClickEventData => {
      if (veltButtonClickEventData) {
        if (veltButtonClickEventData.buttonContext?.clickedButtonId === 'toggleCommentPins') {
          if (veltButtonClickEventData.buttonContext?.selections?.ungrouped['toggleCommentPins']) {
            commentElement.showCommentsOnDom();
          } else {
            commentElement.hideCommentsOnDom(); 
          }
        }
      }
    });
    ```
  </Tab>
</Tabs>

### Single Select Button Group

<Tabs>
  <Tab title="React / Next.js">
    ```jsx {6-12} theme={null}
    <VeltWireframe>
      <VeltCommentsSidebarWireframe.Panel>
          <VeltCommentsSidebarWireframe.Header />
          <div className="custom-filter-chip-container">

              <VeltButtonWireframe id="unread" type="single-select" group="custom-filter">
                  <div className="custom-filter-chip-button">Unread</div>
              </VeltButtonWireframe>

              <VeltButtonWireframe id="mentions" type="single-select" group="custom-filter">
                  <div className="custom-filter-chip-button">Mentions</div>
              </VeltButtonWireframe>

          </div>
      </VeltCommentsSidebarWireframe.Panel>
    </VeltWireframe>
    ```

    **Handle the button click event:**

    ```jsx theme={null}
    // Hook
    const veltButtonClickEventData = useVeltEventCallback('veltButtonClick');
    useEffect(() => {
      if (veltButtonClickEventData) {
        if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
          const selectedFilter = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
          if (selectedFilter?.unread) {
            // show unread comments
          } else if (selectedFilter?.mentions) {
            // show comments with mentions
          }
        }
      }
    }, [veltButtonClickEventData]);

    // API Method
    client.on('veltButtonClick').subscribe(veltButtonClickEventData => {
      if (veltButtonClickEventData) {
        if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
          const selectedFilter = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
          if (selectedFilter?.unread) {
            // show unread comments
          } else if (selectedFilter?.mentions) {
            // show comments with mentions
          }
        }
      }
    });
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html {6-12} theme={null}
    <velt-wireframe style="display:none;">
      <velt-comments-sidebar-wireframe-panel>
        <velt-comments-sidebar-wireframe-header></velt-comments-sidebar-wireframe-header>
        <div class="custom-filter-chip-container">

            <velt-button-wireframe id="unread" type="single-select" group="custom-filter">
                <div class="custom-filter-chip-button">Unread</div>
            </velt-button-wireframe>

            <velt-button-wireframe id="mentions" type="single-select" group="custom-filter">
                <div class="custom-filter-chip-button">Mentions</div>
            </velt-button-wireframe>

        </div>
      </velt-comments-sidebar-wireframe-panel>
    </velt-wireframe>
    ```

    **Handle the button click event:**

    ```js theme={null}
    Velt.on('veltButtonClick').subscribe(veltButtonClickEventData => {
      if (veltButtonClickEventData) {
        if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
          const selectedFilter = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
          if (selectedFilter?.unread) {
            // show unread comments
          } else if (selectedFilter?.mentions) {
            // show comments with mentions
          }
        }
      }
    });
    ```
  </Tab>
</Tabs>

### Multi Select Button Group

<Tabs>
  <Tab title="React / Next.js">
    ```jsx {6-12} theme={null}
    <VeltWireframe>
      <VeltCommentsSidebarWireframe.Panel>
          <VeltCommentsSidebarWireframe.Header />
          <div className="custom-filter-chip-container">

              <VeltButtonWireframe id="unread" type="multi-select" group="custom-filter">
                  <div className="custom-filter-chip-button">Unread</div>
              </VeltButtonWireframe>

              <VeltButtonWireframe id="mentions" type="multi-select" group="custom-filter">
                  <div className="custom-filter-chip-button">Mentions</div>
              </VeltButtonWireframe>

          </div>
      </VeltCommentsSidebarWireframe.Panel>
    </VeltWireframe>
    ```

    **Handle the button click event:**

    ```jsx theme={null}
    // Hook
    const veltButtonClickEventData = useVeltEventCallback('veltButtonClick');
    useEffect(() => {
      if (veltButtonClickEventData) {
        if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
          const selections = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
          if (selections?.unread) {
            // show unread comments
          }
          if (selections?.mentions) {
            // show comments with mentions
          }
        }
      }
    }, [veltButtonClickEventData]);

    // API Method
    client.on('veltButtonClick').subscribe(veltButtonClickEventData => {
      if (veltButtonClickEventData) {
        if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
          const selections = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
          if (selections?.unread) {
            // show unread comments
          }
          if (selections?.mentions) {
            // show comments with mentions
          }
        }
      }
    });
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html {6-12} theme={null}
    <velt-wireframe style="display:none;">
      <velt-comments-sidebar-wireframe-panel>
        <velt-comments-sidebar-wireframe-header></velt-comments-sidebar-wireframe-header>
        <div class="custom-filter-chip-container">

            <velt-button-wireframe id="unread" type="multi-select" group="custom-filter">
                <div class="custom-filter-chip-button">Unread</div>
            </velt-button-wireframe>

            <velt-button-wireframe id="mentions" type="multi-select" group="custom-filter">
                <div class="custom-filter-chip-button">Mentions</div>
            </velt-button-wireframe>

        </div>
      </velt-comments-sidebar-wireframe-panel>
    </velt-wireframe>
    ```

    **Handle the button click event:**

    ```js theme={null}
    Velt.on('veltButtonClick').subscribe(veltButtonClickEventData => {
      if (veltButtonClickEventData) {
        if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
          const selections = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
          if (selections?.unread) {
            // show unread comments
          }
          if (selections?.mentions) {
            // show comments with mentions
          }
        }
      }
    });
    ```
  </Tab>
</Tabs>

### Callback Event

The Velt Button Wireframe emits events when users interact with it. You can listen to these events to implement custom behaviors.

* Returns: [VeltButtonClickEvent](/api-reference/sdk/models/data-models#veltbuttonclickevent)

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    // Hook
    const veltButtonClickEventData = useVeltEventCallback('veltButtonClick');
    useEffect(() => {
      if (veltButtonClickEventData) {
        // Handle button click event response
      }
    }, [veltButtonClickEventData]);

    // API Method
    client.on('veltButtonClick').subscribe((veltButtonClickEventData) => {
        // Handle button click event response
    });

    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```js theme={null}
    Velt.on('veltButtonClick').subscribe((veltButtonClickEventData) => {
        // Handle button click event response
    });
    ```
  </Tab>
</Tabs>

### Set Dynamic ID to Velt Button

* You can use template variables to set the id.

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltButtonWireframe id="{annotation.annotationId}" type="button-toggle" />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-button-wireframe id="{annotation.annotationId}" type="button-toggle"></velt-button-wireframe>
    ```
  </Tab>
</Tabs>

### Reset Velt Button State

* Reset the state of Velt Button components programmatically.
* Params: (optional) [VeltResetButtonStateConfig](/api-reference/sdk/models/data-models#veltresetbuttonstateconfig)

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
      // Reset state for a specific button in a given group
      client.resetVeltButtonState({id: 'openSidebar', group: 'multi'});

      // Reset state for all buttons in a given group
      client.resetVeltButtonState({group: 'multi'});

      // Reset state for a specific button in all groups
      client.resetVeltButtonState({id: 'openSidebar'});

      // Reset state for all buttons
      client.resetVeltButtonState();
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```js theme={null}
      // Reset state for a specific button in a given group
      Velt.resetVeltButtonState({id: 'openSidebar', group: 'multi'});

      // Reset state for all buttons in a given group
      Velt.resetVeltButtonState({group: 'multi'});

      // Reset state for a specific button in all groups
      Velt.resetVeltButtonState({id: 'openSidebar'});

      // Reset state for all buttons
      Velt.resetVeltButtonState();
    ```
  </Tab>
</Tabs>