We recommend that you familiarize yourselves with UI Customization Concepts before attempting to modify any components.
Overview
The Comment Sidebar V2 Primitives API provides 56+ granular components that can be used independently to build completely custom sidebar interfaces. Unlike the V1 sidebar’s monolithic structure, every section of the V2 sidebar is an independently importable and composable primitive. Each primitive can be used standalone or composed together for maximum customization flexibility. Key features of the V2 architecture:- Flat primitive components — each UI section is individually replaceable
- Unified filter model — replaces the legacy
minimalFilter+advancedFilterssystem - CDK virtual scroll — renders only the visible viewport slice for smooth performance on large comment sets
- Focused-thread view — opens individual threads in a dedicated view inside the sidebar
- Conditional styling — all primitives support
velt-classconditional styling viaapplyConditionalClasses
The root container
VeltCommentsSidebarV2 remains plural. All standalone sub-primitives use the singular form VeltCommentSidebarV2* (React) / velt-comment-sidebar-…-v2 (HTML).Usage Patterns
Pattern 1: Drop-in Replacement
UseVeltCommentsSidebarV2 as a direct replacement for VeltCommentsSidebar.
- React / Next.js
- Other Frameworks
Pattern 2: Version Prop on Existing Sidebar
Route the existingVeltCommentsSidebar to the V2 implementation by setting version="2".
- React / Next.js
- Other Frameworks
Pattern 3: Compose from Primitives
Build a fully custom sidebar by composing individual primitives.- React / Next.js
- Other Frameworks
Components
The
MinimalActionsDropdown primitive family was removed in this release and replaced by the combined actions filter dropdown, configured via minimal-filters.VeltCommentsSidebarV2
Root container for the V2 sidebar. Provides shared state context to all child primitives viaparentLocalUIState. See VeltCommentsSidebarV2Props for the type definition.
- React / Next.js
- Other Frameworks
| Prop | Type | Default | Description |
|---|---|---|---|
pageMode | boolean | false | Enable page-level comments mode |
focusedThreadMode | boolean | false | Open individual threads in a focused view inside the sidebar |
readOnly | boolean | false | Render the sidebar in read-only mode |
embedMode | string | null | null | Embed the sidebar inside a custom container |
floatingMode | boolean | false | Render the sidebar in floating mode |
position | 'left' | 'right' | 'right' | Anchor position of the sidebar panel |
variant | string | 'sidebar' | Display variant |
forceClose | boolean | true | Force the sidebar closed programmatically |
version | string | - | When set to "2" on VeltCommentsSidebar, routes to the V2 implementation |
onSidebarOpen | (data: any) => void | - | Callback fired when the sidebar opens |
onSidebarClose | (data: any) => void | - | Callback fired when the sidebar closes |
onCommentClick | (data: any) => void | - | Callback fired when a comment item is clicked |
onCommentNavigationButtonClick | (data: any) => void | - | Callback fired when the comment navigation button is clicked |
VeltCommentSidebarV2Skeleton
Loading skeleton displayed while the sidebar content is loading.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2Panel
Main panel container that holds all sidebar content sections: header, list, empty placeholder, page-mode composer, and focused thread.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2Header
Header section of the sidebar panel. Contains the close button, fullscreen button, search, filter button, and filter dropdown.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2CloseButton
Button to close the sidebar panel.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FullscreenButton
Fullscreen toggle in the header; emitsonFullscreenClick when activated.
- React / Next.js
- Other Frameworks
VeltCommentSidebarV2Search
Search container in the header that holds the search icon and input.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2SearchIcon
Search icon rendered inside the search container.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2SearchInput
Text input for searching comments within the sidebar.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterButton
Header button that opens the filter UI; shows an applied-state icon when filters are active.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterButtonAppliedIcon
Icon shown on the filter button when one or more filters are applied.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainer
Root container for the Main Filter bottom-sheet, holding the title, action buttons, group-by control, and section list.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerTitle
Title text for the Main Filter container.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerCloseButton
Button that closes the Main Filter container.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerApplyButton
Button that applies the currently selected filters and closes the container.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerResetButton
Button that clears all selections in the Main Filter container.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerGroupBy
Group-by control that selects how filtered results are grouped.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerSectionList
Scrollable list of filter sections within the Main Filter container.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerSection
Individual filter section containing a label and a field.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerSectionLabel
Label text for a filter section.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerSectionField
Field wrapper for a filter section that hosts the control and its options. Accepts asearchable boolean input that toggles the per-section search box.
- React / Next.js
- Other Frameworks
| Prop | Type | Default | Description |
|---|---|---|---|
searchable | boolean | false | Toggles the per-section search box |
VeltCommentSidebarV2FilterContainerSectionControl
Control surface for a filter section that displays the selected value and toggles the option list. Accepts asearchable boolean input that toggles the per-section search box.
- React / Next.js
- Other Frameworks
| Prop | Type | Default | Description |
|---|---|---|---|
searchable | boolean | false | Toggles the per-section search box |
VeltCommentSidebarV2FilterContainerSectionControlChevron
Chevron indicator showing the open/closed state of a section control.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerSectionControlValue
Displays the currently selected value(s) of a section control.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerSectionControlChipList
List of selected-value chips for a section control.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerSectionControlChip
Individual chip representing a selected value in a section control.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerSectionControlSearch
Per-section search box within a section control. Rendered when the section issearchable.
- React / Next.js
- Other Frameworks
| Prop | Type | Default | Description |
|---|---|---|---|
searchable | boolean | false | Toggles the per-section search box |
VeltCommentSidebarV2FilterContainerSectionOptionList
List of selectable options within a filter section. Accepts asearchable boolean input that toggles the per-section search box.
- React / Next.js
- Other Frameworks
| Prop | Type | Default | Description |
|---|---|---|---|
searchable | boolean | false | Toggles the per-section search box |
VeltCommentSidebarV2FilterContainerSectionOption
Individual selectable option containing a checkbox, name, and count.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerSectionOptionCheckbox
Checkbox indicating whether an option is selected.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerSectionOptionName
Display name for a filter option.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterContainerSectionOptionCount
Count of matching comments for a filter option.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterDropdown
Dropdown menu in the header for filtering comments. Uses the unified filter model that replaces the legacyminimalFilter + advancedFilters system.
- React / Next.js
- Other Frameworks
| Prop | Type | Default | Description |
|---|---|---|---|
type | 'filter' | 'sort' | 'quick' | 'actions' | unset | Scopes which content the dropdown renders. See Filter-dropdown type scoping. |
fields | FilterField[] | [] | Fields shown when type is filter. |
field | string | unset | Single field id — shorthand for a one-field filter dropdown. |
label | string | unset | Trigger label for the dropdown. |
sorts | (string | SidebarSortConfig)[] | [] | Sort options shown when type is sort or actions. |
actions | (string | SidebarQuickFilterConfig)[] | [] | Quick presets/predicates shown when type is quick or actions. |
showCategoryFilters | boolean | unset | Show the built-in category filter sections in the dropdown. |
SidebarMinimalFilterConfig entry from minimalFilters.VeltCommentSidebarV2FilterDropdownTrigger
Trigger button that opens the filter dropdown.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterDropdownContent
Content container for the filter dropdown.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterDropdownContentList
Scrollable list of filter options. Contains filter items and filter categories.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterDropdownContentListItem
Individual filter option within the filter list. Contains an indicator, a label, and a count.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterDropdownContentListItemIndicator
Visual indicator (such as a checkbox or icon) showing the active state of a filter option.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterDropdownContentListItemLabel
Text label for a filter option.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterDropdownContentListItemCount
Count of matching comments shown alongside a filter option.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterDropdownContentListCategory
Group container for organizing filter options into categories.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterDropdownContentListCategoryLabel
Text label for a filter category.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FilterDropdownContentListCategoryContent
Content area within a filter category, rendering the category’s filter items.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2List
Scrollable list of comment threads. Uses CDK virtual scroll to render only the visible viewport slice, enabling smooth performance on large comment sets.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2ListGroupHeader
Group header rendered inside the list to label and separate grouped comment threads.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2ListGroupHeaderLabel
Label text for a list group header.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2ListGroupHeaderCount
Count of comments within a list group.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2ListGroupHeaderChevron
Chevron indicating the expanded/collapsed state of a list group.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2ListGroupHeaderSeparator
Separator rendered between list group headers.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2ListItem
Individual comment thread item rendered within the list.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2EmptyPlaceholder
Placeholder displayed when no comments match the current filter or when the sidebar has no comments. Contains an optional reset-filter button.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2ResetFilterButton
Button that clears all active filters, returning the sidebar to its unfiltered state.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2PageModeComposer
Composer for creating new page-level comments directly from the sidebar. Only visible whenpageMode is enabled.
- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FocusedThread
Container for the focused-thread view that opens when a comment is clicked withfocusedThreadMode enabled. Contains a back button and the dialog container.
- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FocusedThreadBackButton
Back button that exits the focused-thread view and returns to the comment list.- React / Next.js
- Other Frameworks
VeltCommentSidebarV2FocusedThreadDialogContainer
Container that renders the full comment dialog for the focused thread.- React / Next.js
- Other Frameworks
Component Map
All 56 primitives and their corresponding HTML elements:| React Component | HTML Element |
|---|---|
VeltCommentsSidebarV2 | velt-comments-sidebar-v2 |
VeltCommentSidebarV2Skeleton | velt-comment-sidebar-skeleton-v2 |
VeltCommentSidebarV2Panel | velt-comment-sidebar-panel-v2 |
VeltCommentSidebarV2Header | velt-comment-sidebar-header-v2 |
VeltCommentSidebarV2CloseButton | velt-comment-sidebar-close-button-v2 |
VeltCommentSidebarV2FullscreenButton | velt-comment-sidebar-fullscreen-button-v2 |
VeltCommentSidebarV2Search | velt-comment-sidebar-search-v2 |
VeltCommentSidebarV2SearchIcon | velt-comment-sidebar-search-v2-icon |
VeltCommentSidebarV2SearchInput | velt-comment-sidebar-search-v2-input |
VeltCommentSidebarV2FilterButton | velt-comment-sidebar-filter-button-v2 |
VeltCommentSidebarV2FilterButtonAppliedIcon | velt-comment-sidebar-filter-button-v2-applied-icon |
VeltCommentSidebarV2FilterContainer | velt-comment-sidebar-filter-container-v2 |
VeltCommentSidebarV2FilterContainerTitle | velt-comment-sidebar-filter-container-v2-title |
VeltCommentSidebarV2FilterContainerCloseButton | velt-comment-sidebar-filter-container-v2-close-button |
VeltCommentSidebarV2FilterContainerApplyButton | velt-comment-sidebar-filter-container-v2-apply-button |
VeltCommentSidebarV2FilterContainerResetButton | velt-comment-sidebar-filter-container-v2-reset-button |
VeltCommentSidebarV2FilterContainerGroupBy | velt-comment-sidebar-filter-container-v2-group-by |
VeltCommentSidebarV2FilterContainerSectionList | velt-comment-sidebar-filter-container-v2-section-list |
VeltCommentSidebarV2FilterContainerSection | velt-comment-sidebar-filter-container-v2-section |
VeltCommentSidebarV2FilterContainerSectionLabel | velt-comment-sidebar-filter-container-v2-section-label |
VeltCommentSidebarV2FilterContainerSectionField | velt-comment-sidebar-filter-container-v2-section-field |
VeltCommentSidebarV2FilterContainerSectionControl | velt-comment-sidebar-filter-container-v2-section-control |
VeltCommentSidebarV2FilterContainerSectionControlChevron | velt-comment-sidebar-filter-container-v2-section-control-chevron |
VeltCommentSidebarV2FilterContainerSectionControlValue | velt-comment-sidebar-filter-container-v2-section-control-value |
VeltCommentSidebarV2FilterContainerSectionControlChipList | velt-comment-sidebar-filter-container-v2-section-control-chip-list |
VeltCommentSidebarV2FilterContainerSectionControlChip | velt-comment-sidebar-filter-container-v2-section-control-chip |
VeltCommentSidebarV2FilterContainerSectionControlSearch | velt-comment-sidebar-filter-container-v2-section-control-search |
VeltCommentSidebarV2FilterContainerSectionOptionList | velt-comment-sidebar-filter-container-v2-section-option-list |
VeltCommentSidebarV2FilterContainerSectionOption | velt-comment-sidebar-filter-container-v2-section-option |
VeltCommentSidebarV2FilterContainerSectionOptionCheckbox | velt-comment-sidebar-filter-container-v2-section-option-checkbox |
VeltCommentSidebarV2FilterContainerSectionOptionName | velt-comment-sidebar-filter-container-v2-section-option-name |
VeltCommentSidebarV2FilterContainerSectionOptionCount | velt-comment-sidebar-filter-container-v2-section-option-count |
VeltCommentSidebarV2FilterDropdown | velt-comment-sidebar-filter-dropdown-v2 |
VeltCommentSidebarV2FilterDropdownTrigger | velt-comment-sidebar-filter-dropdown-trigger-v2 |
VeltCommentSidebarV2FilterDropdownContent | velt-comment-sidebar-filter-dropdown-content-v2 |
VeltCommentSidebarV2FilterDropdownContentList | velt-comment-sidebar-filter-dropdown-content-list-v2 |
VeltCommentSidebarV2FilterDropdownContentListItem | velt-comment-sidebar-filter-dropdown-content-list-item-v2 |
VeltCommentSidebarV2FilterDropdownContentListItemIndicator | velt-comment-sidebar-filter-dropdown-content-list-item-indicator-v2 |
VeltCommentSidebarV2FilterDropdownContentListItemLabel | velt-comment-sidebar-filter-dropdown-content-list-item-label-v2 |
VeltCommentSidebarV2FilterDropdownContentListItemCount | velt-comment-sidebar-filter-dropdown-content-list-item-count-v2 |
VeltCommentSidebarV2FilterDropdownContentListCategory | velt-comment-sidebar-filter-dropdown-content-list-category-v2 |
VeltCommentSidebarV2FilterDropdownContentListCategoryLabel | velt-comment-sidebar-filter-dropdown-content-list-category-label-v2 |
VeltCommentSidebarV2FilterDropdownContentListCategoryContent | velt-comment-sidebar-filter-dropdown-content-list-category-content-v2 |
VeltCommentSidebarV2List | velt-comment-sidebar-list-v2 |
VeltCommentSidebarV2ListGroupHeader | velt-comment-sidebar-list-group-header-v2 |
VeltCommentSidebarV2ListGroupHeaderLabel | velt-comment-sidebar-list-group-header-v2-label |
VeltCommentSidebarV2ListGroupHeaderCount | velt-comment-sidebar-list-group-header-v2-count |
VeltCommentSidebarV2ListGroupHeaderChevron | velt-comment-sidebar-list-group-header-v2-chevron |
VeltCommentSidebarV2ListGroupHeaderSeparator | velt-comment-sidebar-list-group-header-v2-separator |
VeltCommentSidebarV2ListItem | velt-comment-sidebar-list-item-v2 |
VeltCommentSidebarV2EmptyPlaceholder | velt-comment-sidebar-empty-placeholder-v2 |
VeltCommentSidebarV2ResetFilterButton | velt-comment-sidebar-reset-filter-button-v2 |
VeltCommentSidebarV2PageModeComposer | velt-comment-sidebar-page-mode-composer-v2 |
VeltCommentSidebarV2FocusedThread | velt-comment-sidebar-focused-thread-v2 |
VeltCommentSidebarV2FocusedThreadBackButton | velt-comment-sidebar-focused-thread-back-button-v2 |
VeltCommentSidebarV2FocusedThreadDialogContainer | velt-comment-sidebar-focused-thread-dialog-container-v2 |

