> ## 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

> Add custom action buttons to Velt components with VeltButtonWireframe: buttons, toggles, and select groups.

* 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. E.g. `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

> [tab] 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] 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
>     }
>   }
> });
>
> ```

### Button Toggle

> [tab] 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] 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(); 
>       }
>     }
>   }
> });
> ```

### Single Select Button Group

> [tab] 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] 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
>       }
>     }
>   }
> });
> ```

### Multi Select Button Group

> [tab] 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] 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
>       }
>     }
>   }
> });
> ```

### 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](https://velt.dev/docs/api-reference/sdk/models/data-models.md#veltbuttonclickevent)

> [tab] 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] Other Frameworks
>
> ```js theme={null}
> Velt.on('veltButtonClick').subscribe((veltButtonClickEventData) => {
>     // Handle button click event response
> });
> ```

### Set Dynamic ID to Velt Button

* You can use template variables to set the id.

> [tab] React / Next.js
>
> ```jsx theme={null}
> <VeltButtonWireframe id="{annotation.annotationId}" type="button-toggle" />
> ```

> [tab] Other Frameworks
>
> ```html theme={null}
> <velt-button-wireframe id="{annotation.annotationId}" type="button-toggle"></velt-button-wireframe>
> ```

### Reset Velt Button State

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

> [tab] 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] 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();
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.