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

# Customize Behavior

# Custom filtering, sorting and grouping

* Here is the overview on how it works:
  * Enable custom actions in the comments sidebar.
  * Add [Velt Button Wireframe](/ui-customization/custom-action-component) to the sidebar wireframe.
  * Handle click events and lifecycle events to apply custom filtering, sorting, and grouping logic.
  * Update sidebar data.
* Here are the steps to implement it:

<Steps titleSize="h2">
  <Step title="Enable Custom Actions">
    <Tabs>
      <Tab title="React / Next.js">
        Using Props:

        ```jsx theme={null}
        <VeltCommentsSidebar customActions={true} />
        ```

        Using API:

        ```javascript theme={null}
        const commentElement = client.getCommentElement();
        commentElement.enableSidebarCustomActions();
        commentElement.disableSidebarCustomActions();
        ```
      </Tab>

      <Tab title="Other Frameworks">
        Using Props:

        ```html theme={null}
        <velt-comments-sidebar custom-actions="true"></velt-comments-sidebar>
        ```

        Using API:

        ```javascript theme={null}
        const commentElement = Velt.getCommentElement();
        commentElement.enableSidebarCustomActions();
        commentElement.disableSidebarCustomActions();
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add Velt Buttons and handle click events">
    * Learn more about how to setup [Velt Button Wireframe](/ui-customization/custom-action-component).
    * Set default state using the `active` prop.
    * Handle `veltButtonClick` event to implement custom filtering, sorting, and grouping logic. It returns [VeltButtonClickEvent](/api-reference/sdk/models/data-models#veltbuttonclickevent).

    <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" active={true}>
                      <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}
        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]);
        ```
      </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" active="true">
                    <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) {
                // Custom Filtering | Sorting | Grouping Logic
              }
              if (selections?.mentions) {
                // Custom Filtering | Sorting | Grouping Logic
              }
            }
          }
        });
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Handle Sidebar data lifecycle events">
    * There are two lifecycle events you need to handle to implement custom filtering, sorting, and grouping logic:

      * `commentSidebarDataInit`: Triggered when comment sidebar data is first loaded. It returns [CommentSidebarDataInitEvent](/api-reference/sdk/models/data-models#commentsidebardatainitevent)
      * `commentSidebarDataUpdate`: Triggered when comment sidebar data is updated. It returns [CommentSidebarDataUpdateEvent](/api-reference/sdk/models/data-models#commentsidebardataupdateevent)
        * This event can trigger multiple times when either the comment data or unread comment count changes.

          <Tabs>
            <Tab title="React / Next.js">
              ```jsx theme={null}
              const commentSidebarDataInitEvent: CommentSidebarDataInitEvent = useCommentEventCallback('commentSidebarDataInit');
              const commentSidebarDataUpdateEvent: CommentSidebarDataUpdateEvent = useCommentEventCallback('commentSidebarDataUpdate');

              useEffect(() => {
                if (commentSidebarDataInitEvent) {
                  // Custom Filtering | Sorting | Grouping Logic
                }
              }, [commentSidebarDataInitEvent]);

              useEffect(() => {
                if (commentSidebarDataUpdateEvent) {
                  // Custom Filtering | Sorting | Grouping Logic
                }
              }, [commentSidebarDataUpdateEvent]);
              ```
            </Tab>

            <Tab title="Other Frameworks">
              ```javascript theme={null}
              const commentElement = Velt.getCommentElement();

              commentElement.on('commentSidebarDataInit').subscribe((data) => {
                // Custom Filtering | Sorting | Grouping Logic
              });

              commentElement.on('commentSidebarDataUpdate').subscribe((data) => {
                // Custom Filtering | Sorting | Grouping Logic
              });
              ```
            </Tab>
          </Tabs>
  </Step>

  <Step title="Update sidebar data based on custom logic">
    * Once you have applied your custom filtering, sorting, and grouping logic, create the data an **array** of [CommentSidebarData](/api-reference/sdk/models/data-models#commentsidebardata) objects and set it in the comments sidebar.
    * Use the `options` parameter to control if you want to group the comments or not.

          <Tabs>
            <Tab title="React / Next.js">
              ```jsx theme={null}
              const options = {
                grouping: false
              };

              const customFilterData = [
                {
                  "groupId": "group1",
                  "groupName": "Group 1",
                  "isExpanded": true,
                  "annotations": [
                    {
                        ...annotation1
                    },
                    {
                        ...annotation2
                    },
                  ]
                }
              ];

              const commentElement = client.getCommentElement();
              commentElement.setCommentSidebarData(customFilterData, options);
              ```
            </Tab>

            <Tab title="Other Frameworks">
              ```javascript theme={null}
              const options = {
                grouping: false
              };
              const customFilterData = [
                {
                  "groupId": "group1",
                  "groupName": "Group 1",
                  "isExpanded": true,
                  "annotations": [
                    {
                        ...annotation1
                    },
                    {
                        ...annotation2
                    },
                  ]
                }
              ];
              const commentElement = Velt.getCommentElement();
              commentElement.setCommentSidebarData(customFilterData, options);
              ```
            </Tab>
          </Tabs>
  </Step>
</Steps>

# Navigation

#### onCommentClick

* Listen for click events on comments in the sidebar to trigger actions like navigation.
* The event callback provides access to the clicked comment's annotation object, which includes `location` and `context` data.
* Use this data to update your app's state and navigate to the comment's location.

The event handler receives an object with the following properties:

| Property          | Type              | Description                                      |
| ----------------- | ----------------- | ------------------------------------------------ |
| `documentId`      | string            | ID of the document containing the comment        |
| `location`        | Object            | Location details of the comment                  |
| `targetElementId` | string            | DOM ID of the element the comment is attached to |
| `context`         | Object            | Custom context data associated with the comment  |
| `annotation`      | CommentAnnotation | The full comment annotation object               |

<Tabs>
  <Tab title="React / Next.js">
    ```js theme={null}
     <VeltCommentsSidebar onCommentClick={onCommentClick} /> 

    // event handler for when a comment is clicked on 
    const onCommentClick = (event) => {
      //handle custom navigation by getting location if you have set custom locations
      const { pageId } = event.location;
      //handle custom navigation by getting context if you have added metadata using addContext()
      const { pageId } = event.context;
      yourNavigateToPageMethod(pageId);
    };
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```js theme={null}

    // event handler for when a comment is clicked on 
    const onCommentClick = (event) => {
      console.log('onCommentClick', event.detail);
      //handle custom navigation by getting location if you have set custom locations
      const { pageId } = event.detail.location;
      //handle custom navigation by getting context if you have added metadata using addContext()
      const { pageId } = event.detail.context;
      yourNavigateToPageMethod(pageId);
    };

    const commentElement = document.querySelector('velt-comments-sidebar');
    commentElement.addEventListener('onCommentClick', onCommentClick);
    ```
  </Tab>
</Tabs>

#### onCommentNavigationButtonClick

* This event is triggered when the navigation button in the comment dialog in the Sidebar is clicked.
* Use this event to implement custom navigation logic.

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar onCommentNavigationButtonClick={onCommentNavigationButtonClick} />

      // event handler for when a comment is clicked on 
      const onCommentNavigationButtonClick = (event) => {
        console.log('onCommentNavigationButtonClick', event);
        //handle custom navigation by getting location if you have used Locations
        const { pageId } = event.location;
        //handle custom navigation by getting context if you have used addContext()
        const { pageId } = event.context;
        yourNavigateToPageMethod(pageId);
      };
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```javascript theme={null}
    const commentSidebarElement = document.querySelector('velt-comments-sidebar');
    commentSidebarElement.addEventListener('onCommentNavigationButtonClick', (event) => {
      console.log('onCommentNavigationButtonClick', event.detail);
    });
    ```
  </Tab>
</Tabs>

#### enableSidebarUrlNavigation

* By default, clicking a comment in the sidebar doesn't automatically update the page URL where the comment was added.
* Use this to enable automatic URL navigation when clicking comments in the sidebar.
* If your app's state is more complex, you might need to listen for `onCommentClick` events and implement custom navigation logic.

Default: `false`

<Tabs>
  <Tab title="React / Next.js">
    Using Props:

    ```jsx theme={null}
    <VeltCommentsSidebar urlNavigation={true} />
    ```

    Using API method:

    ```js theme={null}
    const commentElement = client.getCommentElement();
    // to enable sidebar url navigation
    commentElement.enableSidebarUrlNavigation();
    // to disable sidebar url navigation
    commentElement.disableSidebarUrlNavigation();
    ```
  </Tab>

  <Tab title="Other Frameworks">
    Using Props:

    ```js theme={null}
    <velt-comments-sidebar url-navigation="false"></velt-comments-sidebar>
    ```

    Using API method:

    ```js theme={null}
    const commentElement = Velt.getCommentElement();
    commentElement.enableSidebarUrlNavigation();
    commentElement.disableSidebarUrlNavigation();
    ```
  </Tab>
</Tabs>

# UI

#### currentLocationSuffix

* Adds "(this page)" suffix to the group name when the current location matches the group's location.

Default: `false`

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar currentLocationSuffix={true}/>
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```jsx theme={null}
    <velt-comments-sidebar current-location-suffix="true"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### embedMode

* By default, the sidebar will open up from the right corner of the page.
* With embed mode, you can add the sidebar in your component and it will take up the full width and height of its container.
* When in embed mode, the sidebar will not have the close button. You need to implement your own open and close functionality on the host component.

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <div className="sidebar-container">
      <VeltCommentsSidebar embedMode={true} />
    </div>
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```jsx theme={null}
    <div className="sidebar-container">
      <velt-comments-sidebar embed-mode="true"></velt-comments-sidebar>
    </div>
    ```
  </Tab>
</Tabs>

#### excludeLocationIdsFromSidebar

* Use this to filter out comments from certain locations. These comments will not be displayed in the sidebar.

<Tabs>
  <Tab title="React / Next.js">
    Using Props:

    ```jsx theme={null}
    <VeltCommentsSidebar excludeLocationIds={['location1', 'location2']} />
    ```

    Using API:

    ```jsx theme={null}
    const commentElement = client.getCommentElement();
    commentElement.excludeLocationIdsFromSidebar(['location1', 'location2']);
    ```
  </Tab>

  <Tab title="Other Frameworks">
    Using Props:

    ```jsx theme={null}
    <velt-comments-sidebar exclude-location-ids='["location1", "location2"]'></velt-comments-sidebar>
    ```

    Using API:

    ```jsx theme={null}
    const commentElement = Velt.getCommentElement();
    commentElement.excludeLocationIdsFromSidebar(['location1', 'location2']);
    ```
  </Tab>
</Tabs>

#### filterGhostCommentsInSidebar

* Fileter out and hide ghost comments from the Sidebar.

<Tabs>
  <Tab title="React / Next.js">
    **Using Props:**

    ```jsx theme={null}
    // Use either of the following
    <VeltCommentsSidebar filterGhostCommentsInSidebar={true} />
    <VeltSidebarButton filterGhostCommentsInSidebar={true} />
    ```

    **Using APIs:**

    ```javascript theme={null}
    const commentElement = client.getCommentElement();
    commentElement.enableFilterGhostCommentsInSidebar();
    commentElement.disableFilterGhostCommentsInSidebar();
    ```
  </Tab>

  <Tab title="Other Frameworks">
    **Using Props:**

    ```html theme={null}
    <!-- Use either of the following -->
    <velt-comments-sidebar filter-ghost-comments-in-sidebar="true"></velt-comments-sidebar>
    <velt-sidebar-button filter-ghost-comments-in-sidebar="true"></velt-sidebar-button>
    ```

    **Using APIs:**

    ```javascript theme={null}
    const commentElement = Velt.getCommentElement();
    commentElement.enableFilterGhostCommentsInSidebar();
    commentElement.disableFilterGhostCommentsInSidebar();
    ```
  </Tab>
</Tabs>

#### filterPanelLayout

* Change the layout of the filter panel in the sidebar.
* Options: `menu` or `bottomSheet`
  `Default: bottomSheet`

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar filterPanelLayout="menu"/>
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```jsx theme={null}
    <velt-comments-sidebar filter-panel-layout="menu"/>
    ```
  </Tab>
</Tabs>

#### filterOptionLayout

* Change the layout of the filter options in the sidebar filter panel.
* Options:
  * `checkbox`: (default) to show the filter options in a checkbox list
  * `dropdown`: to show the filter options in a searchable dropdown with checklist

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar filterOptionLayout="dropdown"/>
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```jsx theme={null}
    <velt-comments-sidebar filter-option-layout="dropdown"/>
    ```
  </Tab>
</Tabs>

#### filterCount

* Disable comment count on filter options. This leads to better performance.

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar filterCount={false}/>
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar filter-count="false"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### dialogSelection

* When disabled, clicking a comment in the sidebar triggers a click event instead of opening the dialog inline. When combined with custom UX, this allows you to create a Figma-style sidebar experience where comments open at their location on the DOM rather than within the sidebar itself.

Default: `true`

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar dialogSelection={false}/>
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar dialog-selection="false"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### expandOnSelection

* Controls whether comment dialogs automatically expand when selected in the sidebar.

Default: `true`

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar expandOnSelection={false}/>
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar expand-on-selection="false"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### floatingMode

* This makes the sidebar open in an overlay panel over the sidebar button float over the page content.
* If you use this mode make sure you do not add Velt Sidebar Component in your app.

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltSidebarButton floatingMode={true} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```jsx theme={null}
    <velt-sidebar-button floating-mode="true"></velt-sidebar-button>
    ```
  </Tab>
</Tabs>

#### focusedThreadMode

* In this mode, when you click on a comment in the sidebar, it opens the thread in an expanded view within the sidebar itself.
* Other threads and actions like filters, search etc. are hidden behind a back button.
* Enabling this mode also adds a navigation button in the comment dialog. Clicking it will navigate to the comment and trigger a callback. Learn more about it [here](#oncommentnavigationbuttonclick).

<Warning>
  If you had previously used a wireframe for the comment dialog, you will need to add the [navigation button wireframe](/ui-customization/features/async/comments/comment-dialog/wireframes#header) and the [focused thread wireframe](/ui-customization/features/async/comments/comment-sidebar-structure-v2).
</Warning>

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar focusedThreadMode={true} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar focused-thread-mode="true"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### openAnnotationInFocusMode

* When enabled, opens the comment dialog in focus mode when `focusedThreadMode` is enabled and either:
  * The 'reply' button inside the comment dialog is clicked, or
  * A comment is selected via the `selectCommentByAnnotationId(ANNOTATION_ID)` API method
* This requires `focusedThreadMode` to be enabled.
* Type: [`VeltCommentsSidebarProps`](/api-reference/sdk/models/data-models#veltcommentssidebarprops)

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar focusedThreadMode={true} openAnnotationInFocusMode={true} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar focused-thread-mode="true" open-annotation-in-focus-mode="true"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### fullScreen

* Enable full-screen mode for the Comments Sidebar to maximize the viewing area for large volumes of feedback or detailed comment reviews.
* In full-screen mode, the sidebar expands to fill the entire viewport, providing more space to read and manage comments.
* A full-screen button appears in the sidebar header, allowing users to toggle between normal and full-screen modes.
* This feature is particularly useful when working with complex discussions, long comment threads, or when you need to focus exclusively on feedback.

Default: `false`

<Note>
  Full-screen mode only works in default mode. It is not supported in floating mode or embed mode.
</Note>

<Tabs>
  <Tab title="React / Next.js">
    Using Props:

    ```jsx theme={null}
    <VeltCommentsSidebar fullScreen={true} />
    ```

    Using API:

    ```javascript theme={null}
    const commentElement = client.getCommentElement();
    // Enable full-screen mode
    commentElement.enableFullScreenInSidebar();
    // Disable full-screen mode
    commentElement.disableFullScreenInSidebar();
    ```
  </Tab>

  <Tab title="Other Frameworks">
    Using Props:

    ```html theme={null}
    <velt-comments-sidebar full-screen="true"></velt-comments-sidebar>
    ```

    Using API:

    ```javascript theme={null}
    const commentElement = Velt.getCommentElement();
    // Enable full-screen mode
    commentElement.enableFullScreenInSidebar();
    // Disable full-screen mode
    commentElement.disableFullScreenInSidebar();
    ```
  </Tab>
</Tabs>

#### pageMode

* This adds a composer in the sidebar where users can add comments without attaching them to any specific element.

`Default: false`

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar pageMode={true} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```jsx theme={null}
    <velt-comments-sidebar page-mode="true"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### readOnly

* Make comment dialogs in the sidebar read-only to prevent users from editing comments.

Default: `false`

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar readOnly={true} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar read-only="true"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### position

* Change the default direction where the sidebar opens from.
* Options: `left` or `right`
* Default: `right`

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar position="left"/>
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```jsx theme={null}
    <velt-comments-sidebar position="left"/>
    ```
  </Tab>
</Tabs>

#### openCommentSidebar

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    const commentElement = client.getCommentElement();
    commentElement.openCommentSidebar(); // opens the comments side bar
    commentElement.closeCommentSidebar(); // closes the comments side bar
    commentElement.toggleCommentSidebar(); // toggles the comments side bar
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```jsx theme={null}
    const commentElement = Velt.getCommentElement();
    commentElement.openCommentSidebar(); // opens the comments side bar
    commentElement.closeCommentSidebar(); // closes the comments side bar
    commentElement.toggleCommentSidebar(); // toggles the comments side bar
    ```
  </Tab>
</Tabs>

#### forceClose

Force the sidebar to close on outside click, even when opened programmatically via API.

When the sidebar is opened dynamically through the API, outside clicks are normally ignored (expecting you to handle the close yourself). Setting `forceClose={true}` ensures outside clicks will always close the sidebar.

<Note>
  This does not affect embed mode sidebar.
</Note>

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar forceClose={true} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar force-close="true"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### searchPlaceholder

* Customize the placeholder text shown in the search input of the comments sidebar.

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
      <VeltCommentsSidebar searchPlaceholder="New placeholder" />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar search-placeholder="New placeholder"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### commentPlaceholder

Customize the placeholder text for the dialog composer (the comment input that appears in comment dialogs/threads).

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar commentPlaceholder="Add a comment..." />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar comment-placeholder="Add a comment..."></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### replyPlaceholder

Customize the placeholder text for reply input fields in the sidebar.

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar replyPlaceholder="Write a reply..." />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar reply-placeholder="Write a reply..."></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

To customize placeholder text shown when **editing** an existing comment or reply, use `editPlaceholder`, `editCommentPlaceholder`, and `editReplyPlaceholder`. See [`VeltCommentsSidebarProps`](/api-reference/sdk/models/data-models#veltcommentssidebarprops) for details.

#### pageModePlaceholder

Customize the placeholder text for the page mode composer (the comment input used for creating page-level comments).

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar pageModePlaceholder="Add a page comment..." />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar page-mode-placeholder="Add a page comment..."></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### sidebarButtonCountType

* Change the count shown on the sidebar button.
  * `default`: Shows the total count of comments in open and in progress states. (default)
  * `filter`: Shows the count of filtered comments.

<Tabs>
  <Tab title="React / Next.js">
    **Using Props:**

    ```jsx theme={null}
      <VeltCommentsSidebar sidebarButtonCountType="filter" />
      <VeltSidebarButton sidebarButtonCountType="filter" />
    ```

    **Using APIs:**

    ```jsx theme={null}
    const commentElement = useCommentUtils();
    commentElement.setSidebarButtonCountType('filter');
    ```
  </Tab>

  <Tab title="Other Frameworks">
    **Using Props:**

    ```html theme={null}
    <velt-comments-sidebar sidebar-button-count-type="filter"></velt-comments-sidebar>
    <velt-sidebar-button sidebar-button-count-type="filter"></velt-sidebar-button>
    ```

    **Using APIs:**

    ```js theme={null}
    const commentElement = Velt.getCommentElement();
    commentElement.setSidebarButtonCountType('filter');
    ```
  </Tab>
</Tabs>

#### commentCountType

Control whether the sidebar button shows total or unread comment count.

Type: [`CommentCountType`](/api-reference/sdk/models/data-models#commentcounttype)

* `total`: Shows the total number of comments. (default)
* `unread`: Shows only the count of unread comments.

<Tabs>
  <Tab title="React / Next.js">
    **Using Props:**

    ```jsx theme={null}
    <VeltCommentsSidebar commentCountType="unread" />
    <VeltSidebarButton commentCountType="unread" />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    **Using Props:**

    ```html theme={null}
    <velt-comments-sidebar comment-count-type="unread"></velt-comments-sidebar>
    <velt-sidebar-button comment-count-type="unread"></velt-sidebar-button>
    ```
  </Tab>
</Tabs>

#### context

Pass custom context data to page mode composer comments in the sidebar. This will add the provided context object to any comment added via the page mode composer in the sidebar, allowing you to associate additional metadata (such as job IDs, statuses, or other application-specific data) with the comment annotation.

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar context={{ jobId: `job-page-mode`, jobStatus: 'page comment' }} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```javascript theme={null}
    const commentSidebarElement = document.querySelector('velt-comments-sidebar');
    commentSidebarElement?.setAttribute("context", JSON.stringify({ jobId: `job-page-mode`, jobStatus: 'page comment' }));
    ```
  </Tab>
</Tabs>

# System Filters, Sorting and Grouping

#### filterConfig

* Customize the available system filters:

* `location`: Filter comments by location.

* `document`: Filter comments by document.

* `people`: Filter comments by author of comment annotation.

* `involved`: Filter comments by users who are involved in the comment annotation (author, mentioned, assigned).

* `tagged`: Filter comments by users who were tagged/mentioned in the comment. Only available in the latest SDK version.

* `assigned`: Filter comments by users who were assigned to the comment. Only available in the latest SDK version.

* `priority`: Filter comments by priority.

* `category`: Filter comments by category.

* `status`: Filter comments by status.

* You can rename, disable, configure grouping, and multi-select behavior of the filters as needed.

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    const filterConfig = {
      location: {
        enable: true,
        name: "Pages",
        enableGrouping: true,
        multiSelection: true,
        placeholder: "Filter by location",
        order: ['locationId1', 'locationId2', 'locationId3']
      },
      document: {
        enable: true,
        name: "Documents",
        enableGrouping: true,
        placeholder: "Filter by document",
        multiSelection: true,
      },
      people: {
        enable: true,
        name: "Author",
        enableGrouping: true,
        placeholder: "Filter by author",
        multiSelection: true,
      },
      involved: {
        enable: true,
        name: "Involved",
        enableGrouping: false,
        placeholder: "Filter by involved",
        multiSelection: true,
      },
      tagged: {
        enable: true,
        name: "Tagged",
        enableGrouping: false,
        placeholder: "Filter by tagged",
        multiSelection: true,
      },
      assigned: {
        enable: true,
        name: "Assigned",
        enableGrouping: false,
        placeholder: "Filter by assigned",
        multiSelection: true,
      },
      priority: {
        enable: true,
        name: "Priority",
        enableGrouping: false,
        placeholder: "Filter by priority",
        multiSelection: true,
      },
      category: {
        enable: true,
        name: "Category",
        enableGrouping: true,
        placeholder: "Filter by category",
        multiSelection: true,
      },
      status: {
        enable: true,
        name: "Status",
        placeholder: "Filter by status",
        multiSelection: true,
      }
    };
    <VeltCommentsSidebar filterConfig={filterConfig} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```jsx theme={null}
    const filterConfig = {
      location: {
        enable: true,
        name: "Pages",
        enableGrouping: true,
        multiSelection: true,
        order: ['locationId1', 'locationId2', 'locationId3']
      },
      document: {
        enable: true,
        name: "Documents",
        enableGrouping: true,
        multiSelection: true,
      },
      people: {
        enable: true,
        name: "Author",
        enableGrouping: true,
        multiSelection: true,
      },
      involved: {
        enable: true,
        name: "Involved",
        enableGrouping: false,
        multiSelection: true,
      },
      tagged: {
        enable: true,
        name: "Tagged",
        enableGrouping: false,
        multiSelection: true,
      },
      assigned: {
        enable: true,
        name: "Assigned",
        enableGrouping: false,
        multiSelection: true,
      },
      priority: {
        enable: true,
        name: "Priority",
        enableGrouping: false,
        multiSelection: true,
      },
      category: {
        enable: true,
        name: "Category",
        enableGrouping: true,
        multiSelection: true,
      },
      status: {
        enable: true,
        name: "Status",
        multiSelection: true,
      }
    };
    const commentsSidebar = document.querySelector(`velt-comments-sidebar`);
    commentsSidebar?.setAttribute("filter-config", JSON.stringify(filterConfig));
    ```
  </Tab>
</Tabs>

#### groupConfig

* Enable/disable the option to group comments in the sidebar with the `group config` attribute.
* If you use floating mode, you can pass this config in Sidebar Button Component.

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    const groupConfig = {
      enable: true,
      name: "Custom Group By",
    };

    <VeltCommentsSidebar groupConfig={groupConfig} />

    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```jsx theme={null}
    const groupConfig = {
      enable: true,
      name: "Custom Group By",
    };


    const commentsSidebar = document.querySelector(`velt-comments-sidebar`);
    commentsSidebar?.setAttribute("group-config", JSON.stringify(groupConfig));

    ```
  </Tab>
</Tabs>

#### sortOrder

Set default sort order for comments in the sidebar.

Options: `asc` or `desc`

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar sortOrder="asc" />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar sort-order="asc"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### sortBy

Set default sort field for comments in the sidebar.

Options: `createdAt` or `lastUpdated`

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar sortBy="createdAt" />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar sort-by="createdAt"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### setCommentSidebarFilters

* Programmatically set the system filters on the sidebar:

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    const filters = {
      location: [
        { id: 'location1Id' },
        { id: 'location2Id' },
      ],
      document: [
        { id: 'document1Id' },
        { id: 'document2Id' },
      ],
      people: [ // author of comment annotation
        { userId: 'userIdToFilter' },
      ],
      involved: [ // user is author or mentioned or assigned
        { userId: 'userIdToFilter' },
      ],
      tagged: [
        { userId: 'userIdToFilter' },
      ],
      assigned: [
        { userId: 'userIdToFilter' },
      ],
      priority: ['P0', 'P1', 'P2'],
      category: ['bug', 'feedback', 'question'],
      status: ['OPEN', 'IN_PROGRESS', 'RESOLVED'],
    };

    <VeltCommentsSidebar filters={filters} />
    ```

    API Methods:

    ```jsx theme={null}
    const commentElement = client.getCommentElement();
    commentElement.setCommentSidebarFilters(filters);
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```jsx theme={null}
    const filters = {
    	location: [
    		{ id: 'location1Id' },
    		{ id: 'location2Id' },
    	],
      document: [
        { id: 'document1Id' },
        { id: 'document2Id' },
      ],
    	people: [ // author of comment annotation
    		{ userId: 'userIdToFilter' },
    	],
      involved: [ // user is author or mentioned or assigned
        { userId: 'userIdToFilter' },
      ],
      tagged: [
        { userId: 'userIdToFilter' }
      ],
      assigned: [
        { userId: 'userIdToFilter' },
      ],
    	priority: ['P0', 'P1', 'P2'],
      category: ['bug', 'feedback', 'question'],
    	status: ['OPEN', 'IN_PROGRESS', 'RESOLVED'],
    };

    const commentsSidebar = document.querySelector(`velt-comments-sidebar`);
    commentsSidebar?.setAttribute("filters", JSON.stringify(filters));
    ```

    API Methods:

    ```jsx theme={null}
    const commentElement = Velt.getCommentElement();
    commentElement.setCommentSidebarFilters(filters);
    ```
  </Tab>
</Tabs>

#### systemFiltersOperator

* Specify whether the system filters (e.g., "me", "this page") should be combined with an `and` or `or` operator.
* Default: `and`

<Tabs>
  <Tab title="React / Next.js">
    **Using Props:**

    ```tsx theme={null}
    <VeltCommentsSidebar systemFiltersOperator='or' />
    ```

    **Using API:**

    ```ts theme={null}
    const commentElement = client.getCommentElement();
    commentElement.setSystemFiltersOperator('or');
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar system-filters-operator="or"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

#### defaultMinimalFilter

Set the default minimal filter setting for the sidebar. This controls how resolved comments are handled in relation to other filters.

Type: `'all' | 'read' | 'unread' | 'resolved' | 'open' | 'reset' | null`

| Value        | Description                                                                             |
| ------------ | --------------------------------------------------------------------------------------- |
| `'all'`      | (Default) Respects other filters; excludes resolved comments unless explicitly included |
| `'read'`     | Shows only comments that have been read by the current user                             |
| `'unread'`   | Shows only comments that have not been read by the current user                         |
| `'resolved'` | Shows only resolved comments                                                            |
| `'open'`     | Shows only open (unresolved) comments                                                   |
| `'reset'`    | Ignores all filters; shows all comments including resolved                              |
| `null`       | Respects other filters; includes resolved comments (no minimal filter exclusion)        |

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar defaultMinimalFilter="reset" />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar default-minimal-filter="reset"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

***

# V2 Sidebar Behavior

## version prop

Pass `version="2"` on `VeltCommentsSidebar` to route to the V2 implementation without changing imports.

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltCommentsSidebar version="2" />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments-sidebar version="2"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

## Unified Filter Model

The V2 sidebar uses a single `FilterDropdown` that replaces the V1 per-category filter panel. All filter state is managed through the unified dropdown.

* `FilterDropdown.Content.List.Item` — individual filter option with `Indicator` (checkbox/icon) and `Label`.
* `FilterDropdown.Content.List.Category` — groups related filter items under a collapsible heading via `Category.Content`.

## Props

| Prop                           | HTML Attribute      | Type              | Default   | Description                                                  |
| ------------------------------ | ------------------- | ----------------- | --------- | ------------------------------------------------------------ |
| pageMode                       | page-mode           | boolean           | false     | Enables the page-mode composer at the bottom of the panel    |
| focusedThreadMode              | focused-thread-mode | boolean           | false     | Opens a focused thread view on comment click                 |
| readOnly                       | read-only           | boolean           | false     | Disables all write actions                                   |
| embedMode                      | embed-mode          | string \| null    | null      | Embeds the sidebar inline within a container                 |
| floatingMode                   | floating-mode       | boolean           | false     | Renders the sidebar as a floating overlay                    |
| position                       | position            | 'left' \| 'right' | 'right'   | Side of the viewport the sidebar appears on                  |
| variant                        | variant             | string            | 'sidebar' | Layout variant                                               |
| forceClose                     | force-close         | boolean           | true      | Forces the sidebar closed                                    |
| version                        | version             | string            | —         | When set to `"2"`, renders the V2 implementation             |
| onSidebarOpen                  | —                   | Function          | —         | Callback fired when sidebar opens                            |
| onSidebarClose                 | —                   | Function          | —         | Callback fired when sidebar closes                           |
| onCommentClick                 | —                   | Function          | —         | Callback fired when a comment is clicked                     |
| onCommentNavigationButtonClick | —                   | Function          | —         | Callback fired when the comment navigation button is clicked |

For the full [`VeltCommentsSidebarV2Props`](/api-reference/sdk/models/data-models#veltcommentssidebarv2props) type reference, see the data models page.

For wireframe customization, see [Comment Sidebar V2 Structure](/ui-customization/features/async/comments/comment-sidebar-structure-v2).