> ## Documentation Index
> Fetch the complete documentation index at: https://velt-mintlify-e6426361.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Customize Comments Sidebar V2 behavior
> Configure the V2 Comments Sidebar with declarative filters, mini filters, sort, group, and search inputs plus client-side filter APIs for full control.
# Filtering
The V2 sidebar exposes its filter, sort, group, and search behavior declaratively through inputs. Filters and sorts are described as data; the sidebar renders the matching surfaces and applies the selections client-side via [`applyCommentSidebarClientFilters()`](/api-reference/sdk/api/api-methods#applycommentsidebarclientfilters).
There are three filter surfaces, each driven by its own input:
* **`filters`** — the Main Filter bottom-sheet/menu surface.
* **`miniFilters`** — a single header funnel dropdown.
* **`minimalFilters`** — multiple header dropdowns. When present, these replace the single funnel dropdown.
#### filters
* Define the Main Filter panel sections.
* Pass an array of [`FilterField`](/api-reference/sdk/models/data-models#filterfield) to define sections. Built-in fields are referenced by `field` id; custom fields use `valuePath`.
* When passed an object keyed by field (e.g. `{ status: ['open'] }`) instead of `FilterField[]`, it is treated as a set of active filter selections and applied directly.
Default: `[]`
```jsx theme={null}
const filters = [
{ field: 'status' },
{ field: 'assigned' },
{ field: 'authorName', label: 'Written By', valuePath: 'from.name' },
];
```
```html theme={null}
```
**Active-selections object form** — pass an object keyed by field instead of a `FilterField[]` to apply active filter selections directly:
```jsx theme={null}
```
```html theme={null}
```
#### miniFilters
* Render a single header funnel dropdown with one section per field.
Default: `[]`
```jsx theme={null}
```
```html theme={null}
```
#### minimalFilters
* Renders one or more dropdowns in the sidebar header (these replace the single `miniFilters` funnel when present).
* Each entry in the array creates **one dropdown**. The entry's `type` decides what that dropdown contains, and the matching input (`fields`, `sorts`, or `actions`) provides its content.
Default: `[]`
##### Filter-dropdown `type` scoping
| `type` | The dropdown shows | Built from |
| --------- | ---------------------------------------------------------------------- | ------------------- |
| `filter` | Category checkbox sections (e.g. status, priority, assignee) | `fields` |
| `sort` | Single-select sort options (e.g. by date or unread) | `sorts` |
| `quick` | One-click filters (presets and/or path predicates) | `actions` |
| `actions` | A combined menu: a sort group and a quick group separated by a divider | `sorts` + `actions` |
| *(unset)* | Default quick presets plus any configured sections | — |
A **path predicate** is a rule that keeps only comments whose value at a given field path matches. For example, `{ path: 'from.userId', value: '1.1' }` keeps comments authored by the user with id `1.1`. The `value` is a literal (there is no `@me` token), and paths auto-flatten nested arrays (e.g. `comments.taggedUserContacts.contact.userId`).
Each dropdown is rendered by the filter-dropdown primitive ([`VeltCommentSidebarV2FilterDropdown`](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-primitives#veltcommentsidebarv2filterdropdown) / `velt-comment-sidebar-filter-dropdown-v2`).
The examples below show one dropdown per `type`.
**`filter` — category checkboxes** (built from `fields`):
```jsx theme={null}
```
```html theme={null}
```
**`sort` — sort options** (built from `sorts`):
```jsx theme={null}
```
```html theme={null}
```
**`quick` — one-click filters** (built from `actions` — presets and/or path predicates):
```jsx theme={null}
```
```html theme={null}
```
To match several paths in one quick filter, give an action a list of `conditions` plus an `operator`:
```jsx theme={null}
```
```html theme={null}
```
**`actions` — combined sort + quick menu** (built from `sorts` + `actions`, separated by a divider):
```jsx theme={null}
```
```html theme={null}
```
**Combine multiple dropdowns** — pass several entries to render them side by side:
```jsx theme={null}
```
```html theme={null}
```
Prefer configuring dropdowns through `minimalFilters` as shown above. If you need to place or restyle a dropdown directly in your own markup, you can set these same inputs on the filter-dropdown primitive — see [Comment Sidebar V2 Primitives](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-primitives#veltcommentsidebarv2filterdropdown).
#### defaultMinimalFilter
* Set the default active quick filter applied on load (one of the `minimalFilters` quick presets).
* Type: `'all' | 'read' | 'unread' | 'resolved' | 'open' | 'assignedToMe' | 'reset'`
```jsx theme={null}
```
```html theme={null}
```
#### filterOperator
* Control how active selections across different filter sections combine.
* Options: `and` or `or`
Default: `and`
```jsx theme={null}
```
```html theme={null}
```
#### filterPanelLayout
* Change the layout of the Main Filter panel.
* Options: `bottomSheet` or `menu`
Default: `bottomSheet`
```jsx theme={null}
```
```html theme={null}
```
#### filterOptionLayout
* Change how options render within a filter section.
* Options: `dropdown` or `checkbox`
Default: `dropdown`
```jsx theme={null}
```
```html theme={null}
```
#### filterCount
* Show per-option facet counts. Disabling improves performance.
Default: `true`
```jsx theme={null}
```
```html theme={null}
```
#### systemFiltersOperator
* Specify whether system filters are combined with an `and` or `or` operator.
Default: `and`
**Using Props:**
```jsx theme={null}
```
**Using API:**
```js theme={null}
const commentElement = client.getCommentElement();
commentElement.setSystemFiltersOperator('or');
```
```html theme={null}
```
#### filterGhostCommentsInSidebar
* Filter out and hide ghost comments from the sidebar.
Default: `false`
**Using Props:**
```jsx theme={null}
```
**Using API:**
```js theme={null}
const commentElement = client.getCommentElement();
commentElement.enableFilterGhostCommentsInSidebar();
commentElement.disableFilterGhostCommentsInSidebar();
```
```html theme={null}
```
#### excludeLocationIds
* Filter out comments from certain locations. These comments are not displayed in the sidebar.
Default: `[]`
**Using Props:**
```jsx theme={null}
```
**Using API:**
```js theme={null}
const commentElement = client.getCommentElement();
commentElement.excludeLocationIdsFromSidebar(['location1', 'location2']);
```
```html theme={null}
```
#### customActions
* Enable custom actions in the sidebar so you can add your own wireframe-driven controls.
Default: `false`
**Using Props:**
```jsx theme={null}
```
**Using API:**
```js theme={null}
const commentElement = client.getCommentElement();
commentElement.enableSidebarCustomActions();
commentElement.disableSidebarCustomActions();
```
```html theme={null}
```
#### applyCommentSidebarClientFilters
* Apply client-provided `CommentSidebarFilters` to a set of annotations, honoring the current `systemFiltersOperator`.
```jsx theme={null}
const commentElement = client.getCommentElement();
const filtered = commentElement.applyCommentSidebarClientFilters(annotations, filters);
```
```js theme={null}
const commentElement = Velt.getCommentElement();
const filtered = commentElement.applyCommentSidebarClientFilters(annotations, filters);
```
# Sorting
#### sortBy
* Set the default sort field. This sets the default sort, it does not render a sort dropdown.
* Type: [`SortBy`](/api-reference/sdk/models/data-models#sortby) — a built-in preset (e.g. `'date'`, `'unread'`) or a custom field key / dot-path (e.g. `'comments.createdAt'`).
```jsx theme={null}
```
```html theme={null}
```
#### sortOrder
* Set the default sort direction.
* Type: [`SortOrder`](/api-reference/sdk/models/data-models#sortorder) (`'asc' | 'desc'`)
```jsx theme={null}
```
```html theme={null}
```
#### sortData
* Provide a custom-field sort path used when sorting by a custom field.
```jsx theme={null}
```
```html theme={null}
```
# Grouping
#### groupConfig
* Configure grouping in the sidebar. Grouping defaults to by-location when enabled.
```jsx theme={null}
```
```html theme={null}
```
# 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.
```jsx theme={null}
const onCommentClick = (event) => {
const { pageId } = event.location;
yourNavigateToPageMethod(pageId);
};
```
```js theme={null}
const onCommentClick = (event) => {
const { pageId } = event.detail.location;
yourNavigateToPageMethod(pageId);
};
const commentElement = document.querySelector('velt-comments-sidebar-v2');
commentElement.addEventListener('onCommentClick', onCommentClick);
```
#### onCommentNavigationButtonClick
* Triggered when the navigation button in the comment dialog in the sidebar is clicked.
* Use this event to implement custom navigation logic.
```jsx theme={null}
const onCommentNavigationButtonClick = (event) => {
const { pageId } = event.location;
yourNavigateToPageMethod(pageId);
};
```
```js theme={null}
const commentSidebarElement = document.querySelector('velt-comments-sidebar-v2');
commentSidebarElement.addEventListener('onCommentNavigationButtonClick', (event) => {
console.log('onCommentNavigationButtonClick', event.detail);
});
```
#### urlNavigation
* Enable automatic URL navigation when clicking comments in the sidebar.
* By default, clicking a comment doesn't update the page URL where the comment was added.
Default: `false`
**Using Props:**
```jsx theme={null}
```
**Using API:**
```js theme={null}
const commentElement = client.getCommentElement();
commentElement.enableSidebarUrlNavigation();
commentElement.disableSidebarUrlNavigation();
```
```html theme={null}
```
`enableUrlNavigation` is a deprecated alias for `urlNavigation`. Prefer `urlNavigation`.
#### queryParamsComments
* Sync the selected comment to URL query params.
Default: `false`
```jsx theme={null}
```
```html theme={null}
```
# UI
#### pageMode
* Adds a composer in the sidebar where users can add comments without attaching them to any specific element.
Default: `false`
```jsx theme={null}
```
```html theme={null}
```
#### focusedThreadMode
* When you click a comment in the sidebar, it opens the thread in an expanded view within the sidebar itself.
* Other threads and actions like filters and search are hidden behind a back button.
* Enabling this mode also adds a navigation button in the comment dialog.
Default: `false`
```jsx theme={null}
```
```html theme={null}
```
#### openAnnotationInFocusMode
* When enabled, opens the comment dialog in focus mode when `focusedThreadMode` is enabled and either the reply button is clicked or a comment is selected via `selectCommentByAnnotationId()`.
* Requires `focusedThreadMode` to be enabled.
Default: `false`
```jsx theme={null}
```
```html theme={null}
```
#### readOnly
* Make comment dialogs in the sidebar read-only to prevent users from editing comments.
Default: `false`
```jsx theme={null}
```
```html theme={null}
```
#### embedMode
* Add the sidebar inline within your component; it takes up the full width and height of its container.
* In embed mode, the sidebar does not have a close button. Implement your own open/close on the host component.
Default: `null`
```jsx theme={null}
```
```html theme={null}
```
#### floatingMode
* Open the sidebar in an overlay panel that floats over the page content.
* If you use this mode, do not add the sidebar component to your app separately.
Default: `false`
```jsx theme={null}
```
```html theme={null}
```
#### position
* Change the side of the viewport the sidebar opens from.
* Options: `left` or `right`
Default: `right`
```jsx theme={null}
```
```html theme={null}
```
#### variant
* Set the layout variant of the sidebar.
Default: `sidebar`
```jsx theme={null}
```
```html theme={null}
```
#### dialogVariant
* Set the variant for the embedded comment dialog rendered in the list.
Default: `sidebar`
```jsx theme={null}
```
```html theme={null}
```
#### focusedThreadDialogVariant
* Set the variant for the focused-thread dialog.
Default: `sidebar`
```jsx theme={null}
```
```html theme={null}
```
#### pageModeComposerVariant
* Set the variant for the page-mode composer.
Default: `sidebar`
```jsx theme={null}
```
```html theme={null}
```
#### forceClose
* Force the sidebar to close on outside click, even when opened programmatically via API.
Default: `true`
This does not affect embed mode sidebar.
```jsx theme={null}
```
```html theme={null}
```
#### fullScreen
* Add a fullscreen toggle button to the header. In fullscreen mode the sidebar expands to fill the viewport.
* Observe state changes with the `onFullscreenClick` event.
Default: `false`
**Using Props:**
```jsx theme={null}
console.log('fullscreen', e)} />
```
**Using API:**
```js theme={null}
const commentElement = client.getCommentElement();
commentElement.enableFullScreenInSidebar();
commentElement.disableFullScreenInSidebar();
```
```html theme={null}
```
#### fullExpanded
* Render the sidebar fully expanded.
Default: `false`
```jsx theme={null}
```
```html theme={null}
```
#### shadowDom
* Render the sidebar body inside a shadow root for style isolation.
* Shadow-DOM isolation is enabled by default. Opt out by setting `shadow-dom="false"` or calling `disableSidebarShadowDOM()`.
```jsx theme={null}
```
```html theme={null}
```
#### currentLocationSuffix
* Adds a "(this page)" suffix to the group name when the current location matches the group's location.
Default: `false`
```jsx theme={null}
```
```html theme={null}
```
#### dialogSelection
* When disabled, clicking a comment in the sidebar triggers a click event instead of opening the dialog inline.
Default: `true`
```jsx theme={null}
```
```html theme={null}
```
#### expandOnSelection
* Control whether comment dialogs automatically expand when selected in the sidebar.
Default: `true`
```jsx theme={null}
```
```html theme={null}
```
#### searchPlaceholder
* Customize the placeholder text shown in the search input of the sidebar.
Default: `Search comments`
```jsx theme={null}
```
```html theme={null}
```
#### commentPlaceholder
* Customize the placeholder text for the dialog composer (the comment input that appears in comment dialogs/threads).
```jsx theme={null}
```
```html theme={null}
```
#### replyPlaceholder
* Customize the placeholder text for reply input fields in the sidebar.
```jsx theme={null}
```
```html theme={null}
```
#### pageModePlaceholder
* Customize the placeholder text for the page-mode composer.
```jsx theme={null}
```
```html theme={null}
```
#### editPlaceholder
* Customize the placeholder text shown when editing an existing comment or reply.
* Use `editCommentPlaceholder` for the first comment and `editReplyPlaceholder` for replies; both take precedence over `editPlaceholder`.
```jsx theme={null}
```
```html theme={null}
```
#### sidebarButtonCountType
* Change what the sidebar button count reflects.
* `default`: total count of comments in open and in-progress states.
* `filter`: count of filtered comments.
**Using Props:**
```jsx theme={null}
```
**Using API:**
```js theme={null}
const commentElement = client.getCommentElement();
commentElement.setSidebarButtonCountType('filter');
```
```html theme={null}
```
#### context
* Pass custom context data to page-mode composer comments in the sidebar. The provided context object is attached to any comment added via the page-mode composer.
Default: `null`
```jsx theme={null}
```
```js theme={null}
const commentSidebarElement = document.querySelector('velt-comments-sidebar-v2');
commentSidebarElement?.setAttribute('context', JSON.stringify({ jobId: 'job-page-mode', jobStatus: 'page comment' }));
```
#### Virtual scrolling
* The V2 list uses virtual scrolling. Tune it with `measuredSize` (estimated row size in px), `minBufferPx`, and `maxBufferPx`.
Defaults: `measuredSize` = `220`, `minBufferPx` = `1000`, `maxBufferPx` = `2000`
```jsx theme={null}
```
```html theme={null}
```
# Events
#### onSidebarOpen
* Callback fired when the sidebar opens.
```jsx theme={null}
console.log('opened', data)} />
```
```js theme={null}
const sidebar = document.querySelector('velt-comments-sidebar-v2');
sidebar.addEventListener('onSidebarOpen', (e) => console.log('opened', e.detail));
```
#### onSidebarClose
* Callback fired when the sidebar closes.
```jsx theme={null}
console.log('closed', data)} />
```
```js theme={null}
const sidebar = document.querySelector('velt-comments-sidebar-v2');
sidebar.addEventListener('onSidebarClose', (e) => console.log('closed', e.detail));
```
# Sidebar controls
#### openCommentSidebar / closeCommentSidebar / toggleCommentSidebar
* Programmatically open, close, or toggle the sidebar.
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.openCommentSidebar();
commentElement.closeCommentSidebar();
commentElement.toggleCommentSidebar();
```
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.openCommentSidebar();
commentElement.closeCommentSidebar();
commentElement.toggleCommentSidebar();
```
For V2 wireframe and primitive customization, see [Comment Sidebar V2 Structure](/ui-customization/features/async/comments/comment-sidebar-structure-v2) and [Comment Sidebar V2 Primitives](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-primitives). The sidebar is shadow-DOM isolated by default.