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(). 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 to define sections. Built-in fields are referenced by field id; custom fields use valuePath.
When passed a CommentSidebarFilters object (e.g. { status: ['OPEN'] }) instead of FilterField[], it is treated as active filter selections. Included keys replace their current selections, omitted keys are preserved, and Reset clears all selections. A present-but-empty array clears just that field; an empty object {} clears all selections.

Default: []

React / Next.js
Other Frameworks

const filters = [
  { field: 'status' },
  { field: 'assigned' },
  { field: 'authorName', label: 'Written By', valuePath: 'from.name' },
];

<VeltCommentsSidebarV2 filters={filters} />

<velt-comments-sidebar-v2></velt-comments-sidebar-v2>
<script>
  const sidebar = document.querySelector('velt-comments-sidebar-v2');
  sidebar.filters = [
    { field: 'status' },
    { field: 'assigned' },
    { field: 'authorName', label: 'Written By', valuePath: 'from.name' },
  ];
</script>

Active-selections object form — pass a CommentSidebarFilters object instead of a FilterField[] to apply active filter selections. The values render as checked options in the filter panel and are cleared by Reset:

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2
  filters={{
    status: ['OPEN'],
    people: [{ userId: '1.1' }, { userId: '2.3' }],
  }}
/>

<velt-comments-sidebar-v2></velt-comments-sidebar-v2>
<script>
  const sidebar = document.querySelector('velt-comments-sidebar-v2');
  sidebar.filters = {
    status: ['OPEN'],
    people: [{ userId: '1.1' }, { userId: '2.3' }],
  };
</script>

default status selection

On first load, the Status field starts with Open and every In Progress status selected, so the sidebar shows active comments by default. These selections appear as checked options in the Main Filter panel, and users can clear them like any other filter. The sidebar skips this default selection when:

Filter state was restored from sessionStorage.
You supplied a status selection through setCommentSidebarFilters().
The user has already changed the Status selection.

If the status catalog loads after the sidebar renders and the user hasn’t touched the Status field, the default selection refreshes to match the catalog’s current Open and In Progress statuses.

To show resolved and terminal comments, select All, clear the Status field, or use Reset. Clearing other fields doesn’t affect resolved-comment visibility, and Reset doesn’t re-apply the default statuses.

priority “Not set” option

The default Priority field includes a Not set option for comments without a priority. A custom FilterField with includeUnset: false omits this option.

setCommentSidebarFilters

Use setCommentSidebarFilters() to apply client-provided values as selected options in the sidebar. Each call replaces selections for keys it includes and preserves omitted keys:

Pass an empty array to clear one field.
Pass an empty object ({}) to clear every selected field.
Use Reset in the Main Filter panel to clear client-provided selections.

Facet counts remain absolute within the page-scoped annotation set instead of shrinking around the client-provided selections. The Main Filter badge includes these selections. A non-empty selection also filters when its field is not displayed in the panel; empty undeclared fields are ignored, and declared fields are not duplicated. Values are normalized as follows:

location: by id, falling back to locationName
people, assigned, tagged, and involved: by userId, falling back to email
status, priority, and category: by the provided values without normalization
accessModes: by comment visibility ('public' or 'private')
version: by id
Custom fields: string values or objects containing id and name

React / Next.js
Other Frameworks

import { useVeltClient } from '@veltdev/react';

const { client } = useVeltClient();
const commentElement = client.getCommentElement();

commentElement.setCommentSidebarFilters({
  status: ['OPEN'],
  involved: [{ userId: 'user-123' }],
  location: [{ locationName: 'Home' }],
});

commentElement.setCommentSidebarFilters({ location: [] }); // Clear one field
commentElement.setCommentSidebarFilters({}); // Clear all fields

const commentElement = Velt.getCommentElement();

commentElement.setCommentSidebarFilters({
  status: ['OPEN'],
  involved: [{ userId: 'user-123' }],
  location: [{ locationName: 'Home' }],
});

commentElement.setCommentSidebarFilters({ location: [] }); // Clear one field
commentElement.setCommentSidebarFilters({}); // Clear all fields

location identity

The sidebar identifies a location by its id, falling back to locationName when the id is null, undefined, or an empty string. An id of 0 remains valid, numeric annotation ids compare with equivalent string filter values, and id takes precedence when both fields are present. This identity is used consistently by grouping, location filter options and matching, page mode, and client filters. Comments without any location context appear in the Others group.

people filter identity

People, Involved, Assigned, and Tagged options are keyed by userId and use the person’s name as the label, with an email fallback. Records containing only an email do not create filter options, preventing duplicate options when another record for the same person contains a userId.

miniFilters

Render a single header funnel dropdown with one section per field.

Default: []

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 miniFilters={[{ field: 'status' }, { field: 'priority' }, { field: 'involved' }]} />

<velt-comments-sidebar-v2></velt-comments-sidebar-v2>
<script>
  const sidebar = document.querySelector('velt-comments-sidebar-v2');
  sidebar['mini-filters'] = [{ field: 'status' }, { field: 'priority' }, { field: 'involved' }];
</script>

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 / velt-comment-sidebar-filter-dropdown-v2). The examples below show one dropdown per type. filter — category checkboxes (built from fields):

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 minimalFilters={[{ type: 'filter', fields: [{ field: 'status' }, { field: 'priority' }] }]} />

<velt-comments-sidebar-v2 minimal-filters='[{"type":"filter","fields":[{"field":"status"},{"field":"priority"}]}]'></velt-comments-sidebar-v2>

sort — sort options (built from sorts):

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 minimalFilters={[{ type: 'sort', sorts: ['date', 'unread'] }]} />

<velt-comments-sidebar-v2 minimal-filters='[{"type":"sort","sorts":["date","unread"]}]'></velt-comments-sidebar-v2>

quick — one-click filters (built from actions — presets and/or path predicates):

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2
  minimalFilters={[
    { type: 'quick', actions: ['open', 'resolved', { label: 'Written By Me', path: 'from.userId', value: '1.1' }] },
  ]}
/>

<velt-comments-sidebar-v2 minimal-filters='[{"type":"quick","actions":["open","resolved",{"label":"Written By Me","path":"from.userId","value":"1.1"}]}]'></velt-comments-sidebar-v2>

To match several paths in one quick filter, give an action a list of conditions plus an operator:

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2
  minimalFilters={[
    {
      type: 'quick',
      actions: [{
        label: 'Involved',
        operator: 'or',
        conditions: [
          { path: 'from.userId', value: '1.1' },
          { path: 'assignedTo.userId', value: '1.1' },
          { path: 'comments.taggedUserContacts.contact.userId', value: '1.1' },
        ],
      }],
    },
  ]}
/>

<velt-comments-sidebar-v2
  minimal-filters='[{"type":"quick","actions":[{"label":"Involved","operator":"or","conditions":[{"path":"from.userId","value":"1.1"},{"path":"assignedTo.userId","value":"1.1"},{"path":"comments.taggedUserContacts.contact.userId","value":"1.1"}]}]}]'>
</velt-comments-sidebar-v2>

actions — combined sort + quick menu (built from sorts + actions, separated by a divider):

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2
  minimalFilters={[
    {
      type: 'actions',
      sorts: ['date', 'unread'],
      actions: [
        { preset: 'resolved', label: 'Show resolved comments' },
        { label: 'Only your mentions', path: 'comments.taggedUserContacts.contact.userId', value: '1.1' },
      ],
    },
  ]}
/>

<velt-comments-sidebar-v2
  minimal-filters='[{"type":"actions","sorts":["date","unread"],"actions":[{"preset":"resolved","label":"Show resolved comments"},{"label":"Only your mentions","path":"comments.taggedUserContacts.contact.userId","value":"1.1"}]}]'>
</velt-comments-sidebar-v2>

Combine multiple dropdowns — pass several entries to render them side by side:

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2
  minimalFilters={[
    { type: 'filter', fields: [{ field: 'status' }] },
    { type: 'sort', sorts: ['date', 'unread'] },
    { type: 'quick', actions: ['open', 'resolved'] },
  ]}
/>

<velt-comments-sidebar-v2 minimal-filters='[{"type":"filter","fields":[{"field":"status"}]},{"type":"sort","sorts":["date","unread"]},{"type":"quick","actions":["open","resolved"]}]'></velt-comments-sidebar-v2>

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.

defaultMinimalFilter

Set the default active quick filter applied on load (one of the minimalFilters quick presets).
Type: 'all' | 'read' | 'unread' | 'resolved' | 'open' | 'assignedToMe' | 'reset'

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 defaultMinimalFilter="open" />

<velt-comments-sidebar-v2 default-minimal-filter="open"></velt-comments-sidebar-v2>

The all, unread, read, open, and assignedToMe presets hide terminal statuses, such as Resolved, by default. If you explicitly select a terminal status in a status field filter, that selection overrides the preset and the matching comments appear.

filterOperator

Control how active selections across different filter sections combine.
Options: and or or
This directly configures the Comment Sidebar V2 filter engine. The shared systemFiltersOperator input and API update the same effective operator.

Default: and

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 filterOperator="or" />

<velt-comments-sidebar-v2 filter-operator="or"></velt-comments-sidebar-v2>

filterPanelLayout

Change the layout of the Main Filter panel.
Options: bottomSheet or menu

Default: bottomSheet

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 filterPanelLayout="menu" />

<velt-comments-sidebar-v2 filter-panel-layout="menu"></velt-comments-sidebar-v2>

filterOptionLayout

Change how options render within a filter section.
Options: dropdown or checkbox

Default: dropdown

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 filterOptionLayout="checkbox" />

<velt-comments-sidebar-v2 filter-option-layout="checkbox"></velt-comments-sidebar-v2>

filterCount

Show per-option facet counts. Counts remain absolute within the current page-scoped annotation set and do not shrink around selections supplied through setCommentSidebarFilters(). Disabling improves performance.

Default: true

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 filterCount={false} />

<velt-comments-sidebar-v2 filter-count="false"></velt-comments-sidebar-v2>

systemFiltersOperator

Specify whether different filter fields are combined with an and or or operator in the sidebar filter engine. Values within a single field always match with OR.
Applies to client filters set via setCommentSidebarFilters() as well, including a value set before the sidebar initializes and changes made at runtime.
An explicit filterOperator set during initialization is preserved instead of being overwritten by the shared operator’s initial default value.

Default: and

React / Next.js
Other Frameworks

Using Props:

<VeltCommentsSidebarV2 systemFiltersOperator="or" />

Using API:

const commentElement = client.getCommentElement();
commentElement.setSystemFiltersOperator('or');

<velt-comments-sidebar-v2 system-filters-operator="or"></velt-comments-sidebar-v2>

const commentElement = Velt.getCommentElement();
commentElement.setSystemFiltersOperator('or');

filterGhostCommentsInSidebar

Filter out and hide ghost comments from the sidebar.

Default: false

React / Next.js
Other Frameworks

Using Props:

<VeltCommentsSidebarV2 filterGhostCommentsInSidebar={true} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableFilterGhostCommentsInSidebar();
commentElement.disableFilterGhostCommentsInSidebar();

<velt-comments-sidebar-v2 filter-ghost-comments-in-sidebar="true"></velt-comments-sidebar-v2>

excludeLocationIds

Filter out comments from certain locations. These comments are not displayed in the sidebar.

Default: []

React / Next.js
Other Frameworks

Using Props:

<VeltCommentsSidebarV2 excludeLocationIds={['location1', 'location2']} />

Using API:

const commentElement = client.getCommentElement();
commentElement.excludeLocationIdsFromSidebar(['location1', 'location2']);

<velt-comments-sidebar-v2 exclude-location-ids='["location1", "location2"]'></velt-comments-sidebar-v2>

customActions

Enable custom actions in the sidebar so you can add your own wireframe-driven controls.

Default: false

React / Next.js
Other Frameworks

Using Props:

<VeltCommentsSidebarV2 customActions={true} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableSidebarCustomActions();
commentElement.disableSidebarCustomActions();

<velt-comments-sidebar-v2 custom-actions="true"></velt-comments-sidebar-v2>

applyCommentSidebarClientFilters

Apply client-provided CommentSidebarFilters to a set of annotations, honoring the current systemFiltersOperator.

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
const filtered = commentElement.applyCommentSidebarClientFilters(annotations, filters);

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 — a built-in preset (e.g. 'date', 'unread') or a custom field key / dot-path (e.g. 'comments.createdAt').

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 sortBy="comments.createdAt" />

<velt-comments-sidebar-v2 sort-by="comments.createdAt"></velt-comments-sidebar-v2>

sortOrder

Set the default sort direction.
Type: SortOrder ('asc' | 'desc')

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 sortOrder="desc" />

<velt-comments-sidebar-v2 sort-order="desc"></velt-comments-sidebar-v2>

Grouping

groupConfig

Configure grouping in the sidebar. Grouping defaults to by-location when enabled.
For location grouping, the current and additional-location groups start expanded while other location groups start collapsed. For document grouping, the current document starts expanded while other documents start collapsed.
Status, priority, and custom-field groups start expanded.
Explicit user expansion takes precedence over explicit collapse, which takes precedence over the grouping default. Both overrides persist in sessionStorage.
A real location change resets the overrides so the new current group expands. The initial location emitted during a reload preserves restored overrides.

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 groupConfig={{ enable: true, groupBy: 'location' }} />

<velt-comments-sidebar-v2></velt-comments-sidebar-v2>
<script>
  const sidebar = document.querySelector('velt-comments-sidebar-v2');
  sidebar.setAttribute('group-config', JSON.stringify({ enable: true, groupBy: 'location' }));
</script>

commentClick

Subscribe to the commentClick event to listen for click events on comments in the sidebar list, to trigger actions like navigation.
Payload is CommentClickEvent, which exposes the clicked annotation, documentId, location, targetElementId, and context.

React / Next.js
Other Frameworks

import { useCommentEventCallback } from '@veltdev/react';
import { useEffect } from 'react';

const commentClick = useCommentEventCallback('commentClick');
useEffect(() => {
  if (commentClick) {
    console.log(commentClick.annotation, commentClick.documentId, commentClick.targetElementId);
    const pageId = commentClick.location?.pageId;
    if (pageId) {
      yourNavigateToPageMethod(pageId);
    }
  }
}, [commentClick]);

const commentElement = Velt.getCommentElement();
commentElement.on('commentClick').subscribe((event) => {
  console.log(event?.annotation, event?.documentId, event?.targetElementId);
  const pageId = event?.location?.pageId;
  if (pageId) {
    yourNavigateToPageMethod(pageId);
  }
});

commentNavigationButtonClick

Subscribe to the commentNavigationButtonClick event, triggered when the navigation (“go to”) button on a sidebar comment is clicked.
Use this event to implement custom navigation logic. Payload is CommentNavigationButtonClickEvent, which exposes the same fields as CommentClickEvent (annotation, documentId, location, targetElementId, context).

React / Next.js
Other Frameworks

import { useCommentEventCallback } from '@veltdev/react';
import { useEffect } from 'react';

const commentNav = useCommentEventCallback('commentNavigationButtonClick');
useEffect(() => {
  if (commentNav) {
    console.log(commentNav.annotation, commentNav.documentId, commentNav.targetElementId);
    const pageId = commentNav.location?.pageId;
    if (pageId) {
      yourNavigateToPageMethod(pageId);
    }
  }
}, [commentNav]);

const commentElement = Velt.getCommentElement();
commentElement.on('commentNavigationButtonClick').subscribe((event) => {
  console.log(event?.annotation, event?.documentId, event?.targetElementId);
  const pageId = event?.location?.pageId;
  if (pageId) {
    yourNavigateToPageMethod(pageId);
  }
});

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

React / Next.js
Other Frameworks

Using Props:

<VeltCommentsSidebarV2 urlNavigation={true} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableSidebarUrlNavigation();
commentElement.disableSidebarUrlNavigation();

<velt-comments-sidebar-v2 url-navigation="true"></velt-comments-sidebar-v2>

queryParamsComments

Sync the selected comment to URL query params.

Default: false

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 queryParamsComments={true} />

<velt-comments-sidebar-v2 query-params-comments="true"></velt-comments-sidebar-v2>

UI

pageMode

Adds a composer in the sidebar where users can add comments without attaching them to any specific element.
The list is scoped using the current location identity, so a location with only locationName behaves the same as an id-based location.

Default: false

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 pageMode={true} />

<velt-comments-sidebar-v2 page-mode="true"></velt-comments-sidebar-v2>

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

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 focusedThreadMode={true} />

<velt-comments-sidebar-v2 focused-thread-mode="true"></velt-comments-sidebar-v2>

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

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 focusedThreadMode={true} openAnnotationInFocusMode={true} />

<velt-comments-sidebar-v2 focused-thread-mode="true" open-annotation-in-focus-mode="true"></velt-comments-sidebar-v2>

readOnly

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

Default: false

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 readOnly={true} />

<velt-comments-sidebar-v2 read-only="true"></velt-comments-sidebar-v2>

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

React / Next.js
Other Frameworks

<div className="sidebar-container">
  <VeltCommentsSidebarV2 embedMode={true} />
</div>

<div class="sidebar-container">
  <velt-comments-sidebar-v2 embed-mode="true"></velt-comments-sidebar-v2>
</div>

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

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 floatingMode={true} />

<velt-comments-sidebar-v2 floating-mode="true"></velt-comments-sidebar-v2>

position

Change the side of the viewport the sidebar opens from.
Options: left or right

Default: right

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 position="left" />

<velt-comments-sidebar-v2 position="left"></velt-comments-sidebar-v2>

variant

Set the layout variant of the sidebar.

Default: sidebar

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 variant="inline" />

<velt-comments-sidebar-v2 variant="inline"></velt-comments-sidebar-v2>

dialogVariant

Set the variant for the embedded comment dialog rendered in the list.

Default: sidebar

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 dialogVariant="sidebar" />

<velt-comments-sidebar-v2 dialog-variant="sidebar"></velt-comments-sidebar-v2>

focusedThreadDialogVariant

Set the variant for the focused-thread dialog.

Default: sidebar

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 focusedThreadDialogVariant="sidebar" />

<velt-comments-sidebar-v2 focused-thread-dialog-variant="sidebar"></velt-comments-sidebar-v2>

pageModeComposerVariant

Set the variant for the page-mode composer.

Default: sidebar

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 pageModeComposerVariant="sidebar" />

<velt-comments-sidebar-v2 page-mode-composer-variant="sidebar"></velt-comments-sidebar-v2>

forceClose

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

Default: true

This does not affect embed mode sidebar.

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 forceClose={true} />

<velt-comments-sidebar-v2 force-close="true"></velt-comments-sidebar-v2>

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

React / Next.js
Other Frameworks

Using Props:

<VeltCommentsSidebarV2 fullScreen={true} onFullscreenClick={(e) => console.log('fullscreen', e)} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableFullScreenInSidebar();
commentElement.disableFullScreenInSidebar();

<velt-comments-sidebar-v2 full-screen="true"></velt-comments-sidebar-v2>
<script>
  const sidebar = document.querySelector('velt-comments-sidebar-v2');
  sidebar.addEventListener('onFullscreenClick', (e) => console.log('fullscreen', e));
</script>

fullExpanded

Render the sidebar fully expanded.

Default: false

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 fullExpanded={true} />

<velt-comments-sidebar-v2 full-expanded="true"></velt-comments-sidebar-v2>

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().

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 shadowDom={false} />

<velt-comments-sidebar-v2 shadow-dom="false"></velt-comments-sidebar-v2>

currentLocationSuffix

Adds a “(This page)” suffix to the group name when the current location matches the group’s location.

Default: false

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 currentLocationSuffix={true} />

<velt-comments-sidebar-v2 current-location-suffix="true"></velt-comments-sidebar-v2>

dialogSelection

When disabled, clicking a comment in the sidebar triggers a click event instead of opening the dialog inline.

Default: true

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 dialogSelection={false} />

<velt-comments-sidebar-v2 dialog-selection="false"></velt-comments-sidebar-v2>

expandOnSelection

Control whether comment dialogs automatically expand when selected in the sidebar.

Default: true

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 expandOnSelection={false} />

<velt-comments-sidebar-v2 expand-on-selection="false"></velt-comments-sidebar-v2>

searchPlaceholder

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

Default: Search comments

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 searchPlaceholder="New placeholder" />

<velt-comments-sidebar-v2 search-placeholder="New placeholder"></velt-comments-sidebar-v2>

commentPlaceholder

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

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 commentPlaceholder="Add a comment..." />

<velt-comments-sidebar-v2 comment-placeholder="Add a comment..."></velt-comments-sidebar-v2>

replyPlaceholder

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

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 replyPlaceholder="Write a reply..." />

<velt-comments-sidebar-v2 reply-placeholder="Write a reply..."></velt-comments-sidebar-v2>

pageModePlaceholder

Customize the placeholder text for the page-mode composer.

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 pageModePlaceholder="Add a page comment..." />

<velt-comments-sidebar-v2 page-mode-placeholder="Add a page comment..."></velt-comments-sidebar-v2>

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.

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2
  editPlaceholder="Edit..."
  editCommentPlaceholder="Edit comment..."
  editReplyPlaceholder="Edit reply..."
/>

<velt-comments-sidebar-v2
  edit-placeholder="Edit..."
  edit-comment-placeholder="Edit comment..."
  edit-reply-placeholder="Edit reply...">
</velt-comments-sidebar-v2>

sidebarButtonCountType

Change what the sidebar button count reflects.
- default: total count of comments in open and in-progress states.
- filter: count of the sidebar’s filtered comments, including 0 for an empty result. The count updates when comments are deleted.
When filterCommentsOnDom is enabled, the same filtered list controls which pins appear on the page.
The current filtered result is preserved while the sidebar is loading. It is cleared when the sidebar is destroyed so a removed sidebar no longer gates the badge or on-page pins.

React / Next.js
Other Frameworks

Using Props:

<VeltCommentsSidebarV2 sidebarButtonCountType="filter" />

Using API:

const commentElement = client.getCommentElement();
commentElement.setSidebarButtonCountType('filter');

<velt-comments-sidebar-v2 sidebar-button-count-type="filter"></velt-comments-sidebar-v2>

const commentElement = Velt.getCommentElement();
commentElement.setSidebarButtonCountType('filter');

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

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 context={{ jobId: 'job-page-mode', jobStatus: 'page comment' }} />

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.
Rows wider than the viewport are clipped to the sidebar width instead of creating a horizontal scrollbar.

Defaults: measuredSize = 220, minBufferPx = 1000, maxBufferPx = 2000

React / Next.js
Other Frameworks

<VeltCommentsSidebarV2 measuredSize={220} minBufferPx={1000} maxBufferPx={2000} />

<velt-comments-sidebar-v2 measured-size="220" min-buffer-px="1000" max-buffer-px="2000"></velt-comments-sidebar-v2>

Events

sidebarOpen

Subscribe to the sidebarOpen event, fired when the sidebar opens. Payload is SidebarOpenEvent.

React / Next.js
Other Frameworks

import { useCommentEventCallback } from '@veltdev/react';
import { useEffect } from 'react';

const sidebarOpen = useCommentEventCallback('sidebarOpen');
useEffect(() => {
  if (sidebarOpen) {
    console.log('opened', sidebarOpen);
  }
}, [sidebarOpen]);

const commentElement = Velt.getCommentElement();
commentElement.on('sidebarOpen').subscribe((event) => {
  console.log('opened', event);
});

sidebarClose

Subscribe to the sidebarClose event, fired when the sidebar closes. Payload is SidebarCloseEvent.

React / Next.js
Other Frameworks

import { useCommentEventCallback } from '@veltdev/react';
import { useEffect } from 'react';

const sidebarClose = useCommentEventCallback('sidebarClose');
useEffect(() => {
  if (sidebarClose) {
    console.log('closed', sidebarClose);
  }
}, [sidebarClose]);

const commentElement = Velt.getCommentElement();
commentElement.on('sidebarClose').subscribe((event) => {
  console.log('closed', event);
});

Sidebar controls

openCommentSidebar / closeCommentSidebar / toggleCommentSidebar

Programmatically open, close, or toggle the sidebar.

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
commentElement.openCommentSidebar();
commentElement.closeCommentSidebar();
commentElement.toggleCommentSidebar();

const commentElement = Velt.getCommentElement();
commentElement.openCommentSidebar();
commentElement.closeCommentSidebar();
commentElement.toggleCommentSidebar();

For V2 customization, see Comment Sidebar V2 Wireframes and Comment Sidebar V2 Primitives. The sidebar is shadow-DOM isolated by default.

​Filtering

​filters

​default status selection

​priority “Not set” option

​setCommentSidebarFilters

​location identity

​people filter identity

​miniFilters

​minimalFilters

Filter-dropdown type scoping

​defaultMinimalFilter

​filterOperator

​filterPanelLayout

​filterOptionLayout

​filterCount

​systemFiltersOperator

​filterGhostCommentsInSidebar

​excludeLocationIds

​customActions

​applyCommentSidebarClientFilters

​Sorting

​sortBy

​sortOrder

​Grouping

​groupConfig

​Navigation

​commentClick

​commentNavigationButtonClick

​urlNavigation

​queryParamsComments

​UI

​pageMode

​focusedThreadMode

​openAnnotationInFocusMode

​readOnly

​embedMode

​floatingMode

​position

​variant

​dialogVariant

​focusedThreadDialogVariant

​pageModeComposerVariant

​forceClose

​fullScreen

​fullExpanded

​shadowDom

​currentLocationSuffix

​dialogSelection

​expandOnSelection

​searchPlaceholder

​commentPlaceholder

​replyPlaceholder

​pageModePlaceholder

​editPlaceholder

​sidebarButtonCountType

​context

​Virtual scrolling

​Events

​sidebarOpen

​sidebarClose

​Sidebar controls

​openCommentSidebar / closeCommentSidebar / toggleCommentSidebar

Filtering

filters

default status selection

priority “Not set” option

setCommentSidebarFilters

location identity

people filter identity

miniFilters

minimalFilters

Filter-dropdown `type` scoping

defaultMinimalFilter

filterOperator

filterPanelLayout

filterOptionLayout

filterCount

systemFiltersOperator

filterGhostCommentsInSidebar

excludeLocationIds

customActions

applyCommentSidebarClientFilters

Sorting

sortBy

sortOrder

Grouping

groupConfig

Navigation

commentClick

commentNavigationButtonClick

urlNavigation

queryParamsComments

UI

pageMode

focusedThreadMode

openAnnotationInFocusMode

readOnly

embedMode

floatingMode

position

variant

dialogVariant

focusedThreadDialogVariant

pageModeComposerVariant

forceClose

fullScreen

fullExpanded

shadowDom

currentLocationSuffix

dialogSelection

expandOnSelection

searchPlaceholder

commentPlaceholder

replyPlaceholder

pageModePlaceholder

editPlaceholder

sidebarButtonCountType

context

Virtual scrolling

Events

sidebarOpen

sidebarClose

Sidebar controls

openCommentSidebar / closeCommentSidebar / toggleCommentSidebar