Skip to main content

​
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 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: [] 
const filters = [
  { field: 'status' },
  { field: 'assigned' },
  { field: 'authorName', label: 'Written By', valuePath: 'from.name' },
];

<VeltCommentsSidebarV2 filters={filters} />
Active-selections object form — pass an object keyed by field instead of a FilterField[] to apply active filter selections directly: 
<VeltCommentsSidebarV2 filters={{ status: ['open'], people: ['1.1', '2.3'] }} />

​
miniFilters

  • Render a single header funnel dropdown with one section per field.
Default: [] 
<VeltCommentsSidebarV2 miniFilters={[{ field: 'status' }, { field: 'priority' }, { field: 'involved' }]} />

​
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
typeThe dropdown showsBuilt from
filterCategory checkbox sections (e.g. status, priority, assignee)fields
sortSingle-select sort options (e.g. by date or unread)sorts
quickOne-click filters (presets and/or path predicates)actions
actionsA combined menu: a sort group and a quick group separated by a dividersorts + 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). See Primitive components for the current primitive list. The examples below show one dropdown per type. filter — category checkboxes (built from fields): 
<VeltCommentsSidebarV2 minimalFilters={[{ type: 'filter', fields: [{ field: 'status' }, { field: 'priority' }] }]} />
sort — sort options (built from sorts): 
<VeltCommentsSidebarV2 minimalFilters={[{ type: 'sort', sorts: ['date', 'unread'] }]} />
quick — one-click filters (built from actions — presets and/or path predicates): 
<VeltCommentsSidebarV2
  minimalFilters={[
    { type: 'quick', actions: ['open', 'resolved', { label: 'Written By Me', path: 'from.userId', value: '1.1' }] },
  ]}
/>
To match several paths in one quick filter, give an action a list of conditions plus an operator: 
<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' },
        ],
      }],
    },
  ]}
/>
actions — combined sort + quick menu (built from sorts + actions, separated by a divider): 
<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' },
      ],
    },
  ]}
/>
Combine multiple dropdowns — pass several entries to render them side by side: 
<VeltCommentsSidebarV2
  minimalFilters={[
    { type: 'filter', fields: [{ field: 'status' }] },
    { type: 'sort', sorts: ['date', 'unread'] },
    { type: 'quick', actions: ['open', 'resolved'] },
  ]}
/>
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 Primitives and Primitive components.

​
defaultMinimalFilter

  • Set the default active quick filter applied on load (one of the minimalFilters quick presets).
  • Type: 'all' | 'read' | 'unread' | 'resolved' | 'open' | 'assignedToMe' | 'reset'
<VeltCommentsSidebarV2 defaultMinimalFilter="open" />

​
filterOperator

  • Control how active selections across different filter sections combine.
  • Options: and or or
Default: and 
<VeltCommentsSidebarV2 filterOperator="or" />

​
filterPanelLayout

  • Change the layout of the Main Filter panel.
  • Options: bottomSheet or menu
Default: bottomSheet 
<VeltCommentsSidebarV2 filterPanelLayout="menu" />

​
filterOptionLayout

  • Change how options render within a filter section.
  • Options: dropdown or checkbox
Default: dropdown 
<VeltCommentsSidebarV2 filterOptionLayout="checkbox" />

​
filterCount

  • Show per-option facet counts. Disabling improves performance.
Default: true 
<VeltCommentsSidebarV2 filterCount={false} />

​
systemFiltersOperator

  • Specify whether system filters are combined with an and or or operator.
Default: and
Using Props:
<VeltCommentsSidebarV2 systemFiltersOperator="or" />
Using API:
const commentElement = client.getCommentElement();
commentElement.setSystemFiltersOperator('or');

​
filterGhostCommentsInSidebar

  • Filter out and hide ghost comments from the sidebar.
Default: false
Using Props:
<VeltCommentsSidebarV2 filterGhostCommentsInSidebar={true} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableFilterGhostCommentsInSidebar();
commentElement.disableFilterGhostCommentsInSidebar();

​
excludeLocationIds

  • Filter out comments from certain locations. These comments are not displayed in the sidebar.
Default: []
Using Props:
<VeltCommentsSidebarV2 excludeLocationIds={['location1', 'location2']} />
Using API:
const commentElement = client.getCommentElement();
commentElement.excludeLocationIdsFromSidebar(['location1', 'location2']);

​
customActions

  • Enable custom actions in the sidebar so you can add your own wireframe-driven controls.
Default: false
Using Props:
<VeltCommentsSidebarV2 customActions={true} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableSidebarCustomActions();
commentElement.disableSidebarCustomActions();

​
applyCommentSidebarClientFilters

  • Apply client-provided CommentSidebarFilters to a set of annotations, honoring the current systemFiltersOperator.
const commentElement = client.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').
<VeltCommentsSidebarV2 sortBy="comments.createdAt" />

​
sortOrder

  • Set the default sort direction.
  • Type: SortOrder ('asc' | 'desc')
<VeltCommentsSidebarV2 sortOrder="desc" />

​
sortData

  • Provide a custom-field sort path used when sorting by a custom field.
<VeltCommentsSidebarV2 sortData="comments.createdAt" />

​
Grouping

​
groupConfig

  • Configure grouping in the sidebar. Grouping defaults to by-location when enabled.
<VeltCommentsSidebarV2 groupConfig={{ enable: true, groupBy: 'location' }} />

​
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.
<VeltCommentsSidebarV2 onCommentClick={onCommentClick} />

const onCommentClick = (event) => {
  const { pageId } = event.location;
  yourNavigateToPageMethod(pageId);
};

​
onCommentNavigationButtonClick

  • Triggered when the navigation button in the comment dialog in the sidebar is clicked.
  • Use this event to implement custom navigation logic.
<VeltCommentsSidebarV2 onCommentNavigationButtonClick={onCommentNavigationButtonClick} />

const onCommentNavigationButtonClick = (event) => {
  const { pageId } = event.location;
  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
Using Props:
<VeltCommentsSidebarV2 urlNavigation={true} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableSidebarUrlNavigation();
commentElement.disableSidebarUrlNavigation();
enableUrlNavigation is a deprecated alias for urlNavigation. Prefer urlNavigation.

​
queryParamsComments

  • Sync the selected comment to URL query params.
Default: false 
<VeltCommentsSidebarV2 queryParamsComments={true} />

​
UI

​
pageMode

  • Adds a composer in the sidebar where users can add comments without attaching them to any specific element.
Default: false 
<VeltCommentsSidebarV2 pageMode={true} />

​
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 
<VeltCommentsSidebarV2 focusedThreadMode={true} />

​
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 
<VeltCommentsSidebarV2 focusedThreadMode={true} openAnnotationInFocusMode={true} />

​
readOnly

  • Make comment dialogs in the sidebar read-only to prevent users from editing comments.
Default: false 
<VeltCommentsSidebarV2 readOnly={true} />

​
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 
<div className="sidebar-container">
  <VeltCommentsSidebarV2 embedMode={true} />
</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 
<VeltCommentsSidebarV2 floatingMode={true} />

​
position

  • Change the side of the viewport the sidebar opens from.
  • Options: left or right
Default: right 
<VeltCommentsSidebarV2 position="left" />

​
variant

  • Set the layout variant of the sidebar.
Default: sidebar 
<VeltCommentsSidebarV2 variant="inline" />

​
dialogVariant

  • Set the variant for the embedded comment dialog rendered in the list.
Default: sidebar 
<VeltCommentsSidebarV2 dialogVariant="sidebar" />

​
focusedThreadDialogVariant

  • Set the variant for the focused-thread dialog.
Default: sidebar 
<VeltCommentsSidebarV2 focusedThreadDialogVariant="sidebar" />

​
pageModeComposerVariant

  • Set the variant for the page-mode composer.
Default: sidebar 
<VeltCommentsSidebarV2 pageModeComposerVariant="sidebar" />

​
forceClose

  • Force the sidebar to close on outside click, even when opened programmatically via API.
Default: true
This does not affect embed mode sidebar.
<VeltCommentsSidebarV2 forceClose={true} />

​
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:
<VeltCommentsSidebarV2 fullScreen={true} onFullscreenClick={(e) => console.log('fullscreen', e)} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableFullScreenInSidebar();
commentElement.disableFullScreenInSidebar();

​
fullExpanded

  • Render the sidebar fully expanded.
Default: false 
<VeltCommentsSidebarV2 fullExpanded={true} />

​
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().
<VeltCommentsSidebarV2 shadowDom={false} />

​
currentLocationSuffix

  • Adds a “(this page)” suffix to the group name when the current location matches the group’s location.
Default: false 
<VeltCommentsSidebarV2 currentLocationSuffix={true} />

​
dialogSelection

  • When disabled, clicking a comment in the sidebar triggers a click event instead of opening the dialog inline.
Default: true 
<VeltCommentsSidebarV2 dialogSelection={false} />

​
expandOnSelection

  • Control whether comment dialogs automatically expand when selected in the sidebar.
Default: true 
<VeltCommentsSidebarV2 expandOnSelection={false} />

​
searchPlaceholder

  • Customize the placeholder text shown in the search input of the sidebar.
Default: Search comments 
<VeltCommentsSidebarV2 searchPlaceholder="New placeholder" />

​
commentPlaceholder

  • Customize the placeholder text for the dialog composer (the comment input that appears in comment dialogs/threads).
<VeltCommentsSidebarV2 commentPlaceholder="Add a comment..." />

​
replyPlaceholder

  • Customize the placeholder text for reply input fields in the sidebar.
<VeltCommentsSidebarV2 replyPlaceholder="Write a reply..." />

​
pageModePlaceholder

  • Customize the placeholder text for the page-mode composer.
<VeltCommentsSidebarV2 pageModePlaceholder="Add a page comment..." />

​
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.
<VeltCommentsSidebarV2
  editPlaceholder="Edit..."
  editCommentPlaceholder="Edit comment..."
  editReplyPlaceholder="Edit reply..."
/>

​
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:
<VeltCommentsSidebarV2 sidebarButtonCountType="filter" />
Using API:
const commentElement = client.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 
<VeltCommentsSidebarV2 context={{ 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 
<VeltCommentsSidebarV2 measuredSize={220} minBufferPx={1000} maxBufferPx={2000} />

​
Events

​
onSidebarOpen

  • Callback fired when the sidebar opens.
<VeltCommentsSidebarV2 onSidebarOpen={(data) => console.log('opened', data)} />

​
onSidebarClose

  • Callback fired when the sidebar closes.
<VeltCommentsSidebarV2 onSidebarClose={(data) => console.log('closed', data)} />

​
Sidebar controls

​
openCommentSidebar / closeCommentSidebar / toggleCommentSidebar

  • Programmatically open, close, or toggle the sidebar.
const commentElement = client.getCommentElement();
commentElement.openCommentSidebar();
commentElement.closeCommentSidebar();
commentElement.toggleCommentSidebar();
For V2 wireframe and primitive customization, start with the Component catalog, then use Wireframe components for the complete slot tree and Primitive components for the primitive list. The sidebar is shadow-DOM isolated by default.