Props (every Velt component)

This page focuses on what you need while customizing UI. Prop value types and object shapes are documented in the canonical Data models reference.

This list is generated from the Velt SDK and is complete for what it covers: a name that isn’t listed here doesn’t exist; don’t guess names. It covers the React component props surface (comments + notifications + presence/cursors + recorder/media + charts + utilities); defaults and runtime behavior live in Behaviors; this page is the name/type index.

The prop INDEX: every prop on every user-facing Velt component, by name + type + a one-line gloss, so you can scan “which prop do I pass for X / what’s it called.” <VeltComments> (the largest surface, 129 props) is Part 1; Part 2 covers all other components (sidebar, dialog, pin, notifications, presence, recorder, …).

This page is the index; defaults and behavior live in Behaviors and the behavior detail pages. Look up a prop here to find its name and type, then read its runtime behavior and interactions there. For data fields and events behind a prop, see Data models; for off-by-default features, see Feature flags; for layout, mode, and custom-data shapes, see Layout config. Also review APIs and Events.

Notes: every prop is optional unless marked (required). Booleans serialize to 'true'/'false' only when explicitly set; array/object props (e.g. customStatus) are JSON-serialized. Components also accept standard HTML attributes (className, style, id, children, ref, key), not re-listed. Generated from each component’s props interface in @veltdev/react; exhaustive.

Part 1: `<VeltComments>`

Core feature toggles

Prop	Type	Description / when to use
`reactions`	boolean	Emoji reactions on comments.
`attachments`	boolean	File attachments on comments.
`attachmentDownload`	boolean	Download button on attachments.
`attachmentNameInMessage`	boolean	Show attachment filename inline in the message.
`allowedFileTypes`	string[]	Whitelist of attachment file types.
`customReactions`	`ReactionMap`	Override the reaction emoji set.
`recordings`	string	Allowed recording types. `"none"` disables; CSV like `"audio,screen"`. Not a boolean.
`recordingTranscription`	boolean	Transcription/summary for recordings.
`recordingCountdown`	boolean	Countdown before recording starts.
`screenshot`	boolean	Screenshot capture in the composer.
`status`	boolean	The status field.
`customStatus`	`{id,color,name,type:'default'\|'ongoing'\|'terminal',lightColor?,svg?,iconUrl?}[]`	Define custom statuses.
`priority`	boolean	The priority field.
`customPriority`	`{id,color,name,lightColor?}[]`	Define custom priorities.
`customCategory`	`{id,color,name}[]`	Define custom categories.
`autoCategorize`	boolean	Auto-categorize comments.
`resolveButton`	boolean	The resolve button.
`resolveStatusAccessAdminOnly`	boolean	Restrict resolve to admins.
`visibilityOptions`	boolean	Per-comment visibility (private/team) options.
`seenByUsers`	boolean	”Seen by” avatars.
`deviceInfo`	boolean	Capture/show device + screen-size info.
`deviceIndicatorOnCommentPins`	boolean	Device-type badge on pins.
`commentIndex`	boolean	Numeric index labels on pins.
`replyAvatars`	boolean	Reply-author avatars on the thread.
`maxReplyAvatars`	number	Max reply avatars before “+N”.
`sidebarButtonOnCommentDialog`	boolean	”Open sidebar” button inside the dialog.
`ghostComments`	boolean	Show comments whose target DOM was removed.
`ghostCommentsIndicator`	boolean	The ghost-comment indicator/message.
`minimap`	boolean	Comments minimap.
`minimapPosition`	string	Minimap corner placement.
`hotkey`	boolean	Keyboard hotkey to add a comment.
`bubbleOnPin`	boolean	Bubble preview on the pin.
`bubbleOnPinHover`	boolean	Bubble preview on pin hover.
`pinDrag`	boolean	Allow dragging pins to reposition.
`pinCursorImage`	string	Custom cursor image while placing a comment.
`commentPinHighlighter`	boolean	Highlight the target element when a pin is active.
`formatOptions`	boolean	Rich-text formatting toolbar.
`deleteOnBackspace`	boolean	Delete comment/attachment via Backspace.
`enterKeyToSubmit`	boolean	Enter submits (vs Cmd/Ctrl+Enter).
`forceCloseAllOnEsc`	boolean	Esc closes all open dialogs.
`scrollToComment`	boolean	Auto-scroll to a selected comment.
`commentTool`	boolean	The floating add-comment tool.
`deleteReplyConfirmation`	boolean	Confirm before deleting a reply.
`deleteThreadWithFirstComment`	boolean	Deleting first comment deletes the thread.
`draftMode`	boolean	Persist unsent composer text as a draft.
`collapsedComments`	boolean	Render comments collapsed initially.
`collapsedRepliesPreview`	boolean	Collapsed preview of replies.
`fullExpanded`	boolean	Render comments fully expanded.
`shortUserName`	boolean	Display shortened user names.
`svgAsImg`	boolean	Render SVGs as `<img>`.
`readOnly`	boolean	Read-only (no add/edit).
`linkCallback`	boolean	Route link clicks through a callback instead of navigating.

Mentions / autocomplete

Prop	Type	Description / when to use
`userMentions`	boolean	@-mention autocomplete.
`customAutocompleteSearch`	boolean	Use your own search/data source for mentions (supply data via `ContactElement`/`AutocompleteElement`).
`paginatedContactList`	boolean	Paginate a large contact list.
`expandMentionGroups`	boolean	Expand groups into members.
`showMentionGroupsFirst`	boolean	Groups above individuals.
`showMentionGroupsOnly`	boolean	Only show groups.
`atHereEnabled`	boolean	Enable the `@here` mention.
`atHereLabel` / `atHereDescription`	string	Label/description for `@here`.
`customListDataOnAnnotation`	`CustomAnnotationDropdownData`	Custom dropdown data at the annotation level.
`customListDataOnComment`	`AutocompleteData`	Custom autocomplete data at the comment level.
`assignToType`	`AssignToType`	Assignee picker UI type.
`autoCompleteScrollConfig`	object	Scroll config for autocomplete lists.
`anonymousEmail`	boolean	Allow anonymous email mentions.

Layout / interaction modes

Prop	Type	Description / when to use
`textMode`	boolean	Text/inline-selection commenting.
`inlineCommentMode`	boolean	Inline comment layout.
`popoverMode`	boolean	Dialog as a popover.
`popoverTriangleComponent`	boolean	Popover caret/triangle.
`floatingCommentDialog`	boolean	Floating (free-positioned) dialog.
`dialogOnHover`	boolean	Open dialog on pin hover.
`dialogOnTargetElementClick`	boolean	Open dialog when the target element is clicked.
`inboxMode`	boolean	Inbox-style listing.
`moderatorMode`	boolean	Moderator capabilities.
`streamMode`	boolean	Stream-style mode (+ `streamViewContainerId`).
`suggestionMode`	boolean	Suggestion (edit-proposal) mode.
`mobileMode`	boolean	Mobile-optimized layout.
`privateCommentMode`	boolean	Private comments.
`persistentCommentMode`	boolean	Always-open persistent composer.
`composerMode`	`'default'\|'expanded'`	Composer expansion.
`multiThread`	boolean	Multiple threads per location.
`groupMatchedComments`	boolean	Group comments on the same target.
`commentsOnDom`	boolean	Anchor comments to DOM elements.
`resolvedCommentsOnDom`	boolean	Also render resolved comments on the DOM.
`filterCommentsOnDom`	boolean	Apply active filters to DOM comments.
`areaComment`	boolean	Area (drag-box) comments.
`unreadIndicatorMode`	`'minimal'\|'verbose'`	Unread-indicator style.
`allowedElementIds` / `allowedElementClassNames` / `allowedElementQuerySelectors`	string[]	Restrict where comments can be placed.
`commentToNearestAllowedElement`	boolean	Snap to the nearest allowed element.
`changeDetectionInCommentMode`	boolean	Extra change detection while in comment mode.
`signInButton` / `upgradeButton`	boolean	Gated-commenting sign-in / upgrade buttons.

Placeholders

Prop	Type
`commentPlaceholder` · `replyPlaceholder` · `editPlaceholder` · `editCommentPlaceholder` · `editReplyPlaceholder`	string

Shadow DOM & dark mode

Prop	Type	Note
`shadowDom`	boolean	Master shadow-DOM wrap. Set `false` to style with selector CSS.
`pinShadowDom` / `dialogShadowDom` / `textCommentToolShadowDom` / `textCommentToolbarShadowDom`	boolean	Per-surface shadow-DOM.
`persistentCommentShadowDom`	boolean	Shadow-DOM the persistent composer.
`darkMode`	boolean	Master dark mode.
`dialogDarkMode`	boolean	Dialog dark mode.
`pinDarkMode` / `textCommentToolDarkMode` / `textCommentToolbarDarkMode`	boolean	Per-surface dark mode.

Callbacks

Prop	Fires on	Note
`onSignIn` / `onUpgrade`	sign-in / upgrade button click
`onCommentAdd` / `onCommentUpdate`	comment added / updated	legacy: prefer the event hooks (`useAddCommentAnnotation`, …)
`onCommentAccept` / `onCommentReject`	suggestion accepted / rejected
`onCopyLink`	comment link copied
`onCustomPinInject`	inject a custom pin element
`onSidebarButtonOnCommentDialogClick`	in-dialog sidebar button click	pairs with `sidebarButtonOnCommentDialog`
`onCommentSelectionChange`	selected comment changes

Deprecated (don’t use)

recordingSummary → use recordingTranscription; multiThreadMode → multiThread; groupMultipleMatch → groupMatchedComments; onCommentAdd/onCommentUpdate → use the event hooks.

For <VeltComments> wireframe slot props such as Composer.ActionButton type, see Wireframe components section 6. For custom-data shapes such as customStatus, customPriority, and customReactions, see Layout config.

Part 2: all other components

Prop names and types are verbatim from each component’s props interface in @veltdev/react. Imported field types (e.g. ContextOptions, CommentSidebarFilterConfig, ReactionMap, NotificationTabConfig) come from @veltdev/types.

Comments: containers & surfaces

VeltCommentsSidebar (V1)

IVeltCommentsSidebarProps

Prop	Type	Description / when to use
embedMode	`boolean`	Render the sidebar inline inside your layout instead of as an overlay.
floatingMode	`boolean`	Float the sidebar over content.
enableUrlNavigation	`boolean`	@deprecated: use `urlNavigation`.
urlNavigation	`boolean`	Sync clicked comment into the URL / navigate on deep link.
queryParamsComments	`boolean`	Drive comment selection via query params.
pageMode	`boolean`	Page-level comments (no pins); composer at sidebar level.
currentLocationSuffix	`boolean`	Append current location to entries.
variant	`string`	Named wireframe variant for the sidebar.
pageModeComposerVariant	`string`	Wireframe variant for the page-mode composer.
dialogVariant	`string`	Wireframe variant for dialogs opened from the sidebar.
shadowDom	`boolean`	Render inside a shadow root (style isolation).
sortData	`'asc' \| 'desc' \| 'none'`	Sort comment list.
filterConfig	`CommentSidebarFilterConfig`	Configure which filter types appear (location/people/priority/category/commentType/status).
groupConfig	`CommentSidebarGroupConfig`	Group comments in the list.
filters	`CommentSidebarFilters`	Apply specific filter values programmatically.
excludeLocationIds	`string[]`	Hide comments belonging to these locations.
openSidebar	`Function`	@deprecated: use `onSidebarOpen`.
onSidebarOpen	`Function`	Callback when sidebar opens.
onSidebarCommentClick	`Function`	@deprecated: use `onCommentClick`.
onCommentClick	`Function`	Callback when a comment row is clicked.
onSidebarClose	`Function`	Callback when sidebar closes.
onCommentNavigationButtonClick	`Function`	Callback for the prev/next navigation buttons.
darkMode	`boolean`	Dark theme.
position	`"right" \| "left"`	Which side the sidebar anchors to.
filterPanelLayout	`'menu' \| 'bottomSheet'`	Filter panel presentation.
customActions	`boolean`	Enable custom action slots.
focusedThreadDialogVariant	`string`	Wireframe variant for the focused-thread dialog.
focusedThreadMode	`boolean`	Open threads in focused mode.
openAnnotationInFocusMode	`boolean`	Open the clicked annotation in focus mode.
searchPlaceholder	`string`	Placeholder for the search input.
filterOptionLayout	`'checkbox' \| 'dropdown'`	Filter option presentation.
filterCount	`boolean`	Show counts next to filters.
fullExpanded	`boolean`	Fully expand thread content.
systemFiltersOperator	`'and' \| 'or'`	Combine system filters with AND/OR.
sidebarButtonCountType	`'default' \| 'filter'`	What the sidebar button count reflects.
filterGhostCommentsInSidebar	`boolean`	Include ghost comments when filtering.
fullScreen	`boolean`	Render full screen.
readOnly	`boolean`	Disable mutations (view-only).
dialogSelection	`boolean`	Allow selecting dialogs.
expandOnSelection	`boolean`	Expand a thread when selected.
context	`{ [key: string]: any }`	Arbitrary context attached to created comments.
defaultMinimalFilter	`SidebarFilterCriteria`	Default minimal-filter criteria.
sortOrder	`SortOrder`	Sort order.
sortBy	`SortBy`	Sort field.
forceClose	`boolean`	Force the sidebar closed.
commentPlaceholder	`string`	Composer placeholder (new comment).
replyPlaceholder	`string`	Composer placeholder (reply).
editPlaceholder	`string`	Edit placeholder (generic).
editCommentPlaceholder	`string`	Edit placeholder (comment).
editReplyPlaceholder	`string`	Edit placeholder (reply).
pageModePlaceholder	`string`	Placeholder for the page-mode composer.

VeltCommentsSidebarV2

IVeltCommentSidebarV2Props (extends HTML attrs)

Prop	Type	Description / when to use
pageMode	`boolean`	Page-level comments.
focusedThreadMode	`boolean`	Open threads in focused mode.
readOnly	`boolean`	View-only.
embedMode	`string`	Embed mode (note: typed `string` in V2, not boolean).
floatingMode	`boolean`	Float over content.
position	`'right' \| 'left'`	Anchor side.
variant	`string`	Sidebar wireframe variant.
forceClose	`boolean`	Force closed.
darkMode	`boolean`	Dark theme.
defaultCondition	`boolean`	Default render condition (visibility gate).
filters	`any`	(V2 filtering) Apply filter values.
miniFilters	`any`	(V2) Mini filter set.
minimalFilters	`any`	(V2) Minimal filter set.
filterOperator	`'and' \| 'or'`	Combine filters.
filterPanelLayout	`'menu' \| 'bottomSheet'`	Filter panel layout.
filterOptionLayout	`'checkbox' \| 'dropdown'`	Filter option layout.
filterCount	`boolean`	Show filter counts.
filterGhostCommentsInSidebar	`boolean`	Include ghost comments.
systemFiltersOperator	`'and' \| 'or'`	System filter operator.
defaultMinimalFilter	`'all' \| 'read' \| 'unread' \| 'resolved' \| 'open' \| 'assignedToMe' \| 'reset' \| null`	Default minimal filter.
excludeLocationIds	`string[]`	Hide locations.
sortBy	`any`	(Sorting) Sort field.
sortOrder	`any`	Sort order.
customActions	`boolean`	(Actions/modes) Enable custom actions.
openAnnotationInFocusMode	`boolean`	Open annotation in focus mode.
urlNavigation	`boolean`	URL navigation.
queryParamsComments	`boolean`	Query-param comment selection.
fullScreen	`boolean`	Full screen.
shadowDom	`boolean`	Shadow root isolation.
fullExpanded	`boolean`	Fully expanded.
dialogSelection	`boolean`	Allow dialog selection.
expandOnSelection	`boolean`	Expand on select.
currentLocationSuffix	`boolean`	Append current location.
sidebarButtonCountType	`'default' \| 'filter'`	Sidebar button count source.
dialogVariant	`string`	(Variants) Dialog wireframe variant.
focusedThreadDialogVariant	`string`	Focused-thread dialog variant.
pageModeComposerVariant	`string`	Page-mode composer variant.
pageModePlaceholder	`string`	(Placeholders) Page-mode composer placeholder.
searchPlaceholder	`string`	Search placeholder.
commentPlaceholder	`string`	New-comment placeholder.
replyPlaceholder	`string`	Reply placeholder.
editPlaceholder	`string`	Edit placeholder.
editCommentPlaceholder	`string`	Edit-comment placeholder.
editReplyPlaceholder	`string`	Edit-reply placeholder.
context	`{ [key: string]: any }`	(Misc/advanced) Context for new comments.
groupConfig	`any`	Grouping config.
measuredSize	`number`	Virtual-scroll measured row size hint.
minBufferPx	`number`	Virtual-scroll min buffer (px).
maxBufferPx	`number`	Virtual-scroll max buffer (px).
onFullscreenClick	`Function`	(Events) Fullscreen toggle clicked: the only callback prop on V2.

V2 dropped the sidebar callback props. onSidebarOpen / onSidebarClose / onCommentClick / onCommentNavigationButtonClick (and the deprecated openSidebar / onSidebarCommentClick) are no longer props on V2: subscribe via the unified event bus instead: useCommentEventCallback('sidebarOpen' | 'sidebarClose' | 'commentClick' | 'commentNavigationButtonClick') (or getCommentElement().on(...)). Only onFullscreenClick remains a prop. V1 still has all the callback props (see the V1 section above).

VeltCommentDialog

IVeltCommentDialogProps (extends HTML attrs)

Prop	Type	Description / when to use
annotationId	`string`	Render the dialog for a specific annotation (standalone use).
multiThreadAnnotationId	`string`	Annotation id within a multi-thread pin.
defaultCondition	`boolean`	Visibility gate (skip the internal show/hide condition: you control it).
inlineCommentSectionMode	`boolean`	Render inside an inline comments section.
commentPinSelected	`boolean`	Whether the source pin is selected.
fullExpanded	`boolean`	Fully expand thread.
shadowDom	`boolean`	Shadow-DOM isolation.
darkMode	`boolean`	Dark theme.
readOnly	`boolean`	View-only.
sidebarMode	`boolean`	Render in sidebar context.
isFocusedThreadEnabled	`boolean`	Enable focused-thread behavior.
openAnnotationInFocusMode	`boolean`	Open in focus mode.
expandOnSelection	`boolean`	Expand when selected.
inlineCommentMode	`boolean`	Inline comment mode.
inboxMode	`boolean`	Inbox rendering mode.
isInsidePdfViewer	`boolean`	Adjust behavior inside a PDF viewer.
multiThread	`boolean`	Multi-thread dialog.
commentComposerMode	`boolean`	Composer-only mode.
dialogSelection	`boolean`	Allow dialog selection.
dialogMode	`boolean`	Dialog mode flag.
focusedThreadMode	`boolean`	Focused-thread mode.
pageModeComposer	`boolean`	Page-mode composer.
messageTruncation	`boolean`	Truncate long messages with show more/less.
initialEditCommentIndex	`number \| string \| null`	Open with a specific comment in edit mode.
messageTruncationLines	`number \| string`	Lines before truncation (with `messageTruncation`).
variant	`string`	Wireframe variant.
composerPosition	`string`	Composer placement.
sortBy	`string`	Sort field.
sortOrder	`string`	Sort order.
commentPinType	`'bubble' \| 'pin' \| 'chart' \| 'text'`	The pin type this dialog belongs to.
containerComponentId	`string`	Id of the container component.
targetElementId	`string`	Anchor element id.
targetComposerElementId	`string`	Composer anchor element id.
locationVersion	`string`	Location version.
locationDisplayName	`string`	Display name for the location.
context	`any`	Context for new comments.
placeholder	`string`	Generic placeholder.
commentPlaceholder	`string`	New-comment placeholder.
replyPlaceholder	`string`	Reply placeholder.
editPlaceholder	`string`	Edit placeholder.
editCommentPlaceholder	`string`	Edit-comment placeholder.
editReplyPlaceholder	`string`	Edit-reply placeholder.
anonymousEmail	`boolean`	Per-dialog override for anonymous email mentions in this annotation context.

VeltMultiThreadCommentDialog

IVeltMultiThreadCommentDialogProps (extends HTML attrs)

Prop	Type	Description / when to use
annotationId	`string`	Annotation id.
multiThreadAnnotationId	`string`	Thread id within the multi-thread pin.
annotation	`any`	Pass the annotation object directly.
user	`any`	Pass the user object directly.
commentPinSelected	`boolean`	Whether the source pin is selected.
commentPinType	`string`	Pin type.
dialogVariant	`string`	Dialog wireframe variant.
variant	`string`	Wireframe variant.
inboxMode	`boolean`	Inbox rendering.
containerComponentId	`string`	Container component id.
context	`any`	Context for new comments.
readOnly	`boolean`	View-only.
defaultCondition	`boolean`	Visibility gate.
onSaveComment	`Function`	Callback fired when a comment is saved.

VeltCommentText

IVeltCommentTextProps (extends HTML attrs)

Prop	Type	Description / when to use
annotationId	`string`	Annotation whose comment text to render.
multiThreadAnnotationId	`string`	Thread id within a multi-thread pin.

VeltCommentThread (IVeltCommentThreadProps: annotationId, annotation, onCommentClick, darkMode, variant, dialogVariant, shadowDom, fullExpanded) is deprecated: use VeltCommentDialog (above) instead. VeltCommentComposer (IVeltCommentComposerProps: darkMode, variant, dialogVariant, shadowDom, context, locationId, documentId, folderId, targetComposerElementId, placeholder, readOnly) renders a standalone composer.

Comments: pins, bubbles, tools

VeltCommentBubble

IVeltCommentBubbleProps (extends HTML attrs)

Prop	Type	Description / when to use
targetCommentElementId	`string`	@deprecated: use `targetElementId`.
targetElementId	`string`	Element the bubble attaches to.
showAvatar	`boolean`	@deprecated: use `avatar`.
avatar	`boolean`	Show commenter avatar on the bubble.
commentBubbleTargetPinHover	`boolean`	Highlight target pin on bubble hover.
shadowDom	`boolean`	Shadow-DOM isolation.
variant	`string`	Bubble wireframe variant.
darkMode	`boolean`	Dark theme.
readOnly	`boolean`	View-only.
commentCountType	`'total' \| 'unread'`	Count shown on the bubble.
context	`{ [key: string]: any }`	Context for new comments.
contextOptions	`ContextOptions`	Context resolution options.
locationId	`string`	Scope to a location.
documentId	`string`	Scope to a document.
folderId	`string`	Scope to a folder.
annotationId	`string`	Bind to a specific annotation.
openDialog	`boolean`	Open the dialog on render.

VeltCommentPin

IVeltCommentPinProps (extends HTML attrs)

Prop	Type	Description / when to use
annotationId	`string`	Annotation the pin represents.
multiThreadAnnotationId	`string`	Thread id within a multi-thread pin.
variant	`string`	Pin wireframe variant.
context	`{ [key: string]: any }`	Context for new comments.
contextOptions	`ContextOptions`	Context resolution options.
locationId	`string`	Scope to a location.
documentId	`string`	Scope to a document.
folderId	`string`	Scope to a folder.
defaultCondition	`boolean`	Visibility gate.

VeltCommentTool

IVeltCommentToolProps (extends HTML attrs)

Prop	Type	Description / when to use
targetCommentElementId	`string`	@deprecated: use `targetElementId`.
targetElementId	`string`	Element to attach the new comment to.
onCommentModeChange	`Function`	Fires when comment mode toggles on/off.
sourceId	`string`	Source identifier.
darkMode	`boolean`	Dark theme.
disabled	`boolean`	Disable the tool.
variant	`string`	Tool wireframe variant.
shadowDom	`boolean`	Shadow-DOM isolation.
context	`{ [key: string]: any }`	Context for new comments.
contextOptions	`ContextOptions`	Context resolution options.
locationId	`string`	Scope to a location.
documentId	`string`	Scope to a document.
folderId	`string`	Scope to a folder.
contextInPageModeComposer	`boolean`	Apply context inside the page-mode composer.

VeltSidebarButton

IVeltSidebarButtonProps (extends HTML attrs)

Prop	Type	Description / when to use
tooltipText	`string`	Button tooltip.
darkMode	`boolean`	Dark theme.
shadowDom	`boolean`	Shadow-DOM isolation.
floatingMode	`boolean`	Float the opened sidebar.
variant	`string`	Button wireframe variant.
pageMode	`boolean`	(Sidebar props) Page-level comments.
sortData	`'asc' \| 'desc' \| 'none'`	Sort comment list.
urlNavigation	`boolean`	URL navigation.
currentLocationSuffix	`boolean`	Append current location.
filterConfig	`CommentSidebarFilterConfig`	Configure filter types.
groupConfig	`CommentSidebarGroupConfig`	Grouping config.
filters	`CommentSidebarFilters`	Apply filter values.
excludeLocationIds	`string[]`	Hide locations.
dialogVariant	`string`	Dialog wireframe variant.
pageModeComposerVariant	`string`	Page-mode composer variant.
sidebarShadowDom	`boolean`	Shadow-DOM for the opened sidebar.
sidebarVariant	`string`	Sidebar wireframe variant.
position	`"right" \| "left"`	Sidebar anchor side.
filterPanelLayout	`'menu' \| 'bottomSheet'`	Filter panel layout.
sidebarButtonCountType	`'default' \| 'filter'`	Count source.
filterGhostCommentsInSidebar	`boolean`	Include ghost comments.
onCommentClick	`Function`	Comment clicked in sidebar.
onSidebarOpen	`Function`	Sidebar opened.
commentCountType	`'total' \| 'unread'`	Count type on the button.
defaultCondition	`boolean`	Visibility gate.

VeltCommentsSidebarButton is a leaner variant of VeltSidebarButton (same props minus variant, sidebarButtonCountType, filterGhostCommentsInSidebar, commentCountType, defaultCondition). VeltCommentsMinimap (IVeltCommentsMinimapProps): position, targetScrollableElementId.

Inline / section components

VeltInlineCommentsSection

IVeltInlineCommentsSectionProps (extends HTML attrs)

Prop	Type	Description / when to use
config	`{ id: string; name?: string }`	Section identity (id + optional name).
targetInlineCommentElementId	`string`	@deprecated: use `targetElementId`.
targetCommentElementId	`string`	@deprecated: use `targetElementId`.
targetElementId	`string`	Element the section attaches to.
darkMode	`boolean`	Dark theme.
variant	`string`	Section wireframe variant.
dialogVariant	`string`	Dialog wireframe variant.
composerVariant	`string`	Composer wireframe variant.
shadowDom	`boolean`	Shadow-DOM isolation.
multiThread	`boolean`	Multi-thread mode.
sortData	`'asc' \| 'desc' \| 'none'`	@deprecated: use `sortBy` and `sortOrder`.
composerPosition	`'top' \| 'bottom'`	Composer placement.
sortBy	`'createdAt' \| 'lastUpdated'`	Sort field.
sortOrder	`'asc' \| 'desc'`	Sort order.
fullExpanded	`boolean`	Fully expand threads.
context	`{ [key: string]: any }`	Context for new comments.
contextOptions	`ContextOptions`	Context resolution options.
locationId	`string`	Scope to a location.
documentId	`string`	Scope to a document.
folderId	`string`	Scope to a folder.
commentPlaceholder	`string`	New-comment placeholder.
replyPlaceholder	`string`	Reply placeholder.
composerPlaceholder	`string`	Composer placeholder.
editPlaceholder	`string`	Edit placeholder.
editCommentPlaceholder	`string`	Edit-comment placeholder.
editReplyPlaceholder	`string`	Edit-reply placeholder.
readOnly	`boolean`	View-only.
anonymousEmail	`boolean`	Per-section override for anonymous email mentions.
messageTruncation	`boolean`	Truncate long messages with show more/less.
messageTruncationLines	`number`	Lines before truncating (with `messageTruncation`).
defaultCondition	`boolean`	Visibility gate.

VeltInlineReactionsSection

IVeltInlineReactionsSectionProps (extends HTML attrs)

Prop	Type	Description / when to use
targetReactionElementId	`string`	Element the reactions section attaches to.
darkMode	`boolean`	Dark theme.
variant	`string`	Section wireframe variant.
shadowDom	`boolean`	Shadow-DOM isolation.
customReactions	`ReactionMap`	Custom emoji/reaction set.

Text & chart comments

VeltTextComment

IVeltTextCommentProps (extends HTML attrs)

Prop	Type	Description / when to use
defaultCondition	`boolean`	Default render condition (visibility gate).
variant	`string`	Wireframe variant.

VeltChartComment

IVeltChartCommentProps (extends HTML attrs)

Prop	Type	Description / when to use
commentMetadata	`{ [key: string]: any }`	Metadata stored on comments placed on the chart.
dialogMetadataTemplate	`string[]`	Fields to surface in the dialog header.
ghostComment	`boolean`	Show comments whose data point is gone.

VeltHighChartComments

IVeltHighChartCommentsProps

Prop	Type	Description / when to use
id	`string` (required)	Chart instance id.
chartComputedData	`any` (required)	Computed point data to anchor comments.
dialogMetadataTemplate	`string[]`	Fields to surface in the dialog header.
Highcharts	`any`	The Highcharts instance to bind to.

VeltNivoChartComments

IVeltNivoChartCommentsProps

Prop	Type	Description / when to use
id	`string` (required)	Chart instance id. Comments are filtered to this chart via `annotation.metadata.id === id`.
chartComputedData	`any`	Computed point data to anchor comments.
dialogMetadataTemplate	`string[]`	Fields to surface in the dialog header.

Notifications

VeltNotificationsPanel

IVeltNotificationsPanelProps

Prop	Type	Description / when to use
darkMode	`boolean`	Dark theme.
onNotificationClick	`Function`	Callback when a notification is clicked.
shadowDom	`boolean`	Shadow-DOM isolation.
variant	`string`	Panel wireframe variant.
tabConfig	`NotificationTabConfig`	Configure tabs (`forYou` / `documents` / `all` / `people`), each `{ name?, enable? }`.
readNotificationsOnForYouTab	`boolean`	Mark read when viewing the For You tab.
panelOpenMode	`NotificationPanelMode`	How the panel opens.
settings	`boolean`	Show settings UI.
selfNotifications	`boolean`	Include the current user’s own notifications.
pageSize	`number`	Notifications per page.
settingsLayout	`NotificationSettingsLayout`	Settings layout.
enableSettingsAtOrganizationLevel	`boolean`	Org-level settings.
defaultCondition	`boolean`	Visibility gate.
enableCrossOrganization	`boolean \| string \| CrossOrganizationConfig`	Cross-org notifications.

VeltNotificationsTool

IVeltNotificationsToolProps (extends HTML attrs)

Prop	Type	Description / when to use
darkMode	`boolean`	Dark theme.
onNotificationClick	`Function`	Notification clicked callback.
shadowDom	`boolean`	Shadow-DOM isolation (tool).
panelShadowDom	`boolean`	Shadow-DOM for the opened panel.
variant	`string`	Tool wireframe variant.
tabConfig	`NotificationTabConfig`	Tab configuration.
panelOpenMode	`'popover' \| 'sidebar'`	How the panel opens.
panelVariant	`string`	Panel wireframe variant.
maxDays	`number`	Max age (days) of notifications to show.
readNotificationsOnForYouTab	`boolean`	Mark read on For You tab.
settings	`boolean`	Show settings.
selfNotifications	`boolean`	Include own notifications.
considerAllNotifications	`boolean`	Consider all notifications for the unread count.
pageSize	`number`	Notifications per page.
settingsLayout	`NotificationSettingsLayout`	Settings layout.
enableSettingsAtOrganizationLevel	`boolean`	Org-level settings.
defaultCondition	`boolean`	Visibility gate.
enableCrossOrganization	`boolean \| string \| CrossOrganizationConfig`	Cross-org notifications.

VeltNotificationsHistoryPanel (IVeltNotificationsHistoryPanelProps): embedMode, onNotificationClick, darkMode.

Presence & cursors

VeltPresence

IVeltPresenceProps

Prop	Type	Description / when to use
maxUsers	`number`	Max avatars to display before overflow.
inactivityTime	`number`	Ms of inactivity before a user is marked inactive.
offlineInactivityTime	`number`	Ms before marking a user offline.
documentParams	`any`	Document params for scoping presence.
location	`any`	Location object for scoping presence.
locationId	`string`	Location id for scoping presence.
onUsersChanged	`Function`	@deprecated: use `onPresenceUserChange`.
onPresenceUserChange	`Function`	Fires when the presence user list changes.
flockMode	`boolean`	Enable flock (follow) mode.
disableFlockNavigation	`boolean`	@deprecated: use `defaultFlockNavigation`.
defaultFlockNavigation	`boolean`	Default flock navigation behavior.
self	`boolean`	Include the current user in the list.
shadowDom	`boolean`	Shadow-DOM isolation.
onNavigate	`(pageInfo: { path: string, url: string, baseUrl: string }) => void`	Navigation callback during flock.
onPresenceUserClick	`(presenceUser: any) => any`	Fires when a presence avatar is clicked.

VeltCursor

IVeltCursorProps (extends HTML attrs)

Prop	Type	Description / when to use
avatarMode	`boolean`	Show user avatars on cursors.
inactivityTime	`number`	Ms before hiding an inactive cursor.
allowedElementIds	`string`	JSON-stringified array of element ids to constrain cursors to. (Stringify your array before passing.)
onCursorUsersChanged	`Function`	@deprecated: use `onCursorUserChange`.
onCursorUserChange	`Function`	Fires when the cursor user list changes.

Reactions

VeltReactionTool

IVeltReactionToolProps

Prop	Type	Description / when to use
videoPlayerId	`string`	Bind the reaction tool to a specific video player.
onReactionToolClick	`Function`	Fires when the reaction tool is clicked.

There is no VeltReactionsToolbar component: reactions are exposed via VeltReactionTool and VeltInlineReactionsSection.

Recorder

VeltRecorderControlPanel

IVeltRecorderControlPanelProps

Prop	Type	Description / when to use
mode	`RecorderLayoutMode`	Layout mode of the control panel.
panelId	`string`	Bind to a specific recorder panel instance.
onRecordedData	`(data: RecordedData) => void`	Callback with recorded data when recording completes.
recordingCountdown	`boolean`	Show a countdown before recording.
recordingTranscription	`boolean`	Enable transcription.
videoEditor	`boolean`	Enable the video editor.
settingsEmbedded	`boolean`	Embed settings in the panel.
autoOpenVideoEditor	`boolean`	Auto-open the editor after recording.
playVideoInFullScreen	`boolean`	Play preview full screen.
retakeOnVideoEditor	`boolean`	Allow retake from the editor.
pictureInPicture	`boolean`	Enable PiP.
maxLength	`number`	Max recording length.
videoEditorTimelinePreview	`boolean`	Timeline preview in the editor.

VeltRecorderPlayer

IVeltRecorderPlayerProps

Prop	Type	Description / when to use
recorderId	`string`	Bind to a specific recording.
onDelete	`Function`	Fires when the recording is deleted.
showSummary	`boolean`	@deprecated: use `summary`.
summary	`boolean`	Show the recording summary.
shadowDom	`boolean`	Shadow-DOM isolation.
videoEditor	`boolean`	Enable the video editor.
playVideoInFullScreen	`boolean`	Play full screen.
retakeOnVideoEditor	`boolean`	Allow retake from the editor.
playbackOnPreviewClick	`boolean`	Start playback on preview click.

VeltRecorderTool (type, panelId, buttonLabel, darkMode, shadowDom, recordingCountdown, variant, retakeOnVideoEditor, pictureInPicture, maxLength) and VeltRecorderNotes (shadowDom, videoEditor, recordingCountdown, recordingTranscription, playVideoInFullScreen, videoEditorTimelinePreview) round out the recorder family.

Media

VeltVideoPlayer

IVeltVideoPlayerProps

Prop	Type	Description / when to use
src	`string`	(required) Video source URL.
darkMode	`boolean`	Dark theme.
sync	`boolean`	Sync playback across collaborators.
commentTool	`boolean`	Enable the in-player comment tool.
shadowDom	`boolean`	Shadow-DOM isolation.

VeltVideoEditor

IVeltVideoEditorProps (extends HTML attrs)

Prop	Type	Description / when to use
darkMode	`boolean`	Dark theme.
variant	`string`	Editor wireframe variant.
blob	`Blob`	Source recording as a `Blob` to edit.
url	`string`	Source recording URL to edit.
annotationId	`string`	Annotation the recording belongs to.
recorderId	`string`	Bind to a specific recording instance.

VeltCommentPlayerTimeline (totalMediaLength, offset, shadowDom, videoPlayerId, onCommentClick, onReactionClick) overlays comment/reaction markers on a media timeline. VeltCanvasComment (IVeltCanvasCommentProps): canvasId (required), position (required).

Huddle

VeltHuddle

IVeltHuddleProps

Prop	Type	Description / when to use
chat	`boolean`	Enable in-huddle chat.
flockModeOnAvatarClick	`boolean`	Enter flock mode when an avatar is clicked.
serverFallback	`boolean`	Use server fallback for the huddle.

VeltHuddleTool (IVeltHuddleToolProps): type, darkMode.

Tags & arrows

Component	Props
`VeltTags`	`pinHighlighterClass` (CSS class for the pin highlighter).
`VeltTagTool`	`targetTagElementId` (element the tag tool attaches to).
`VeltArrows`	no props (`React.FC<any>`, renders `<velt-arrows>`).
`VeltArrowTool`	`darkMode`.

Users / access

VeltUserInviteTool

IVeltUserInviteToolProps (extends HTML attrs)

Prop	Type	Description / when to use
type	`string`	Invite tool type.
source	`string`	Source identifier.
title	`string`	Dialog title.
placeholder	`string`	Input placeholder.
inviteUrl	`string`	Invite URL to share.
accessControlDropdown	`boolean`	Show the access-control dropdown.
documentUserAccessList	`boolean`	Show the document’s user access list.
darkMode	`boolean`	Dark theme.

VeltUserRequestTool (IVeltUserRequestToolProps): type: default 'feedback'; allowed 'feedback' / 'reportBug' / 'contactUs'.

Analytics & utilities

Component	Props
`VeltViewAnalytics`	`type` (`'document' \| 'location'`), `locationId`.
`VeltActivityLog`	`darkMode`, `shadowDom`, `useDummyData`, `variant`.
`VeltSingleEditorModePanel`	`shadowDom`, `variant`, `darkMode`.
`VeltAutocomplete`	`hotkey` (required) (key that triggers it, e.g. `@`), `listData` (required) (`AutocompleteItem[]`).

Data / template utilities

Two small utility components for binding/rendering live data and conditionally rendering markup: used inside custom pin/dialog/wireframe layouts (see Template Variables). All props are optional; both also accept className and id.

VeltData

IVeltDataProps: renders <velt-data>. Binds and renders a single live data value into your markup.

Prop	Type	Description / when to use
path	`string`	Path to the data object to bind to.
field	`string`	The field on that object to render (e.g. `annotation.annotationIndex`).

VeltIf

IVeltIfProps (extends HTML attrs): renders <velt-if>. Conditionally renders its children from a wireframe/feature-state expression.

Prop	Type	Description / when to use
condition	`string`	Expression that gates the children (e.g. `{annotation.status.id} === 'OPEN'`).

The directive form of this: veltIf as a prop/attribute on any wireframe slot: is documented in Template Variables and Wireframe components; VeltIf is the standalone component form.

Deprecated / legacy prop index

Component	Prop	Replacement
VeltComments	onCommentAdd / onCommentUpdate	the event hooks (`useAddCommentAnnotation`, …)
VeltComments	recordingSummary	recordingTranscription
VeltComments	multiThreadMode	multiThread
VeltComments	groupMultipleMatch	groupMatchedComments
VeltCommentThread (component)	None	use `VeltCommentDialog`
VeltCommentsSidebar (V1)	enableUrlNavigation	urlNavigation
VeltCommentsSidebar (V1)	openSidebar	onSidebarOpen
VeltCommentsSidebar (V1)	onSidebarCommentClick	onCommentClick
VeltCommentBubble	targetCommentElementId	targetElementId
VeltCommentBubble	showAvatar	avatar
VeltCommentTool	targetCommentElementId	targetElementId
VeltInlineCommentsSection	targetInlineCommentElementId	targetElementId
VeltInlineCommentsSection	targetCommentElementId	targetElementId
VeltInlineCommentsSection	sortData	sortBy + sortOrder
VeltPresence	onUsersChanged	onPresenceUserChange
VeltPresence	disableFlockNavigation	defaultFlockNavigation
VeltCursor	onCursorUsersChanged	onCursorUserChange
VeltRecorderPlayer	showSummary	summary

Part 3: Layout config and custom data

Everything above is a per-component prop list. This part covers the two config surfaces that need more than a table: the sidebar’s filter configuration, and replacing Velt’s built-in option sets with your own.

Prop before wireframe. If a prop gets you the layout you need (filterPanelLayout="bottomSheet", panelOpenMode="sidebar"), use it. It’s far less work than a wireframe. In non-React frameworks these are kebab-case attributes on the <velt-*> element (filter-panel-layout="bottomSheet").

The sidebar has three filter surfaces: the minimal filter (the quick all/unread/resolved bar), the main filter panel (the full dropdown of categories), and custom filters you define. All are customizable. 1. Choose which filters appear + add your own: the filters prop (a CommentSidebarFilterConfig). It’s a map of filter keys → a FilterTypeConfig:

type FilterTypeConfig = {
  name?: string;            // label shown in the panel
  enable?: boolean;         // show/hide this filter
  multiSelection?: boolean; // allow multiple values
  enableGrouping?: boolean; // group the sidebar list by this filter
  order?: string[];         // option order
  placeholder?: string;
  id?: string;
  type?: 'system' | 'custom';   // 'custom' = your own filter
  options?: { id: string; name: string }[];   // the selectable values
};

Built-in keys: location, document, people, assigned, tagged, involved, priority, status, category, commentType, version. Toggle/relabel/reorder them, and add a custom filter by adding your own key with type: 'custom' + options:

<VeltCommentsSidebarV2
  shadowDom={false}
  filters={{
    status:   { enable: true,  name: "Status", multiSelection: true },
    priority: { enable: false },                         // hide a built-in filter
    severity: {                                          // ← your custom filter
      type: "custom", name: "Severity", multiSelection: true,
      options: [
        { id: "sev1", name: "Sev 1" },
        { id: "sev2", name: "Sev 2" },
      ],
    },
  }}
/>

(miniFilters / minimalFilters configure the quick-bar the same way; groupConfig controls list grouping.) A custom filter matches annotations by the option id you set on them (via customListDataOnAnnotation / annotation metadata). Set filter values programmatically with client.getCommentElement().setCommentSidebarFilters({ status: ["OPEN"], severity: ["sev1"] }). 2. Choose the filter layout (props above): filterPanelLayout ('menu' panel vs 'bottomSheet'), filterOptionLayout ('checkbox' vs 'dropdown'), filterOperator ('and'/'or'), filterCount, defaultMinimalFilter. 3. Fully restyle the filter UI with wireframe slots (Wireframe components). The V2 sidebar exposes: FilterButton (+ AppliedIcon), FilterDropdown (Trigger, Content → List → Item / Category), and FilterContainer (Title, CloseButton, GroupBy, ResetButton, ApplyButton, SectionList → Section → Label / Field → Control(Value, ChipList→Chip, Search, Chevron) / OptionList → Option(Checkbox, Name, Count)). Fill these to build a fully custom filter dropdown / panel while Velt keeps the filtering logic. In wireframes you can read {appliedFiltersCount} and {filterState} to drive your own filter UI. (See Template Variables.)

Same trade as everywhere: config props for which filters + layout (cheapest); wireframe slots to restructure the filter dropdown/panel; the filtering behavior stays Velt’s.

Custom data: your own statuses, priorities, categories, reactions

These props let you replace Velt’s default option sets with your own. They’re a core part of customization: the values flow into the UI (status/priority dropdowns, chips), into the wireframe variables (statusOptions, priorityOptions, customStatusesShown, …), and into the primitive dropdown items (so your custom dialog dropdown shows your statuses). Pass them on VeltComments:

<VeltComments
  customStatus={[
    { id: "OPEN",  name: "Open",  color: "#625DF5", type: "default",  lightColor: "#EEF" },
    { id: "WIP",   name: "In progress", color: "#ECB000", type: "ongoing" },
    { id: "DONE",  name: "Done",  color: "#00C48C", type: "terminal" },
  ]}
  customPriority={[
    { id: "P0", name: "Urgent", color: "#FF7162", lightColor: "#FFF4F2" },
    { id: "P1", name: "Normal", color: "#625DF5" },
  ]}
  customCategory={[{ id: "bug", name: "Bug", color: "#FF7162" }]}
  customReactions={{ "👍": { label: "Thumbs up", emoji: "👍" } }}
/>

Exact shapes:

customStatus: { id, name, color, type: 'default' | 'ongoing' | 'terminal', lightColor?, svg?, iconUrl? }[]: type controls semantics (terminal = resolved-like).
customPriority: { id, name, color, lightColor? }[].
customCategory: { id, name, color }[].
customReactions: a map of emoji → { label, emoji } (a ReactionMap).
customListDataOnAnnotation (a CustomAnnotationDropdownData): the custom chip/dropdown on a thread (powers the CustomAnnotationDropdown slot). Shape:
{ type: 'single' | 'multi'; // single- vs multi-select placeholder?: string; // default 'Select' data: { id: string; label: string }[]; // the selectable options }
The option id is what a custom sidebar filter matches against (see the filters example above): set the option on annotations via this prop, filter by the same id.

customListDataOnComment (an AutocompleteData): custom list on a comment (autocomplete-style). Shape:

{
  hotkey: string;                          // trigger char, e.g. '#'
  description?: string;
  type: 'custom' | 'contact' | 'group';    // default 'custom'
  data: {                                  // AutocompleteItem[]
    id: string; name: string;
    description?: string;
    icon?: { url?: string; svg?: string };
    link?: string; groupId?: string;       // groupId ties an item to a group
  }[];
  groups?: { id: string; name: string }[]; // optional groups
}

When you build a custom status/priority dropdown with primitives (Primitives), this is where the statuses you map over come from. When you read {statusOptions} / {priorityOptions} in a wireframe (Template Variables), these are the values.

Version differences: embedMode is boolean on the V1 sidebar but string on V2. Match the type to the component version you’re using.

​Part 1: <VeltComments>

​Core feature toggles

​Mentions / autocomplete

​Layout / interaction modes

​Placeholders

​Shadow DOM & dark mode

​Callbacks

​Deprecated (don’t use)

​Part 2: all other components

​Comments: containers & surfaces

​VeltCommentsSidebar (V1)

​VeltCommentsSidebarV2

​VeltCommentDialog

​VeltMultiThreadCommentDialog

​VeltCommentText

​Comments: pins, bubbles, tools

​VeltCommentBubble

​VeltCommentPin

​VeltCommentTool

​VeltSidebarButton

​Inline / section components

​VeltInlineCommentsSection

​VeltInlineReactionsSection

​Text & chart comments

​VeltTextComment

​VeltChartComment

​VeltHighChartComments

​VeltNivoChartComments

​Notifications

​VeltNotificationsPanel

​VeltNotificationsTool

​Presence & cursors

​VeltPresence

​VeltCursor

​Reactions

​VeltReactionTool

​Recorder

​VeltRecorderControlPanel

​VeltRecorderPlayer

​Media

​VeltVideoPlayer

​VeltVideoEditor

​Huddle

​VeltHuddle

​Tags & arrows

​Users / access

​VeltUserInviteTool

​Analytics & utilities

​Data / template utilities

​VeltData

​VeltIf

​Deprecated / legacy prop index

​Part 3: Layout config and custom data

​Sidebar filters

​Custom data: your own statuses, priorities, categories, reactions

Part 1: `<VeltComments>`

Core feature toggles

Mentions / autocomplete

Layout / interaction modes

Placeholders

Shadow DOM & dark mode

Callbacks

Deprecated (don’t use)

Part 2: all other components

Comments: containers & surfaces

VeltCommentsSidebar (V1)

VeltCommentsSidebarV2

VeltCommentDialog

VeltMultiThreadCommentDialog

VeltCommentText

Comments: pins, bubbles, tools

VeltCommentBubble

VeltCommentPin

VeltCommentTool

VeltSidebarButton

Inline / section components

VeltInlineCommentsSection

VeltInlineReactionsSection

Text & chart comments

VeltTextComment

VeltChartComment

VeltHighChartComments

VeltNivoChartComments

Notifications

VeltNotificationsPanel

VeltNotificationsTool

Presence & cursors

VeltPresence

VeltCursor

Reactions

VeltReactionTool

Recorder

VeltRecorderControlPanel

VeltRecorderPlayer

Media

VeltVideoPlayer

VeltVideoEditor

Huddle

VeltHuddle

Tags & arrows

Users / access

VeltUserInviteTool

Analytics & utilities

Data / template utilities

VeltData

VeltIf

Deprecated / legacy prop index

Part 3: Layout config and custom data

Sidebar filters

Custom data: your own statuses, priorities, categories, reactions