> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Text Comment Wireframe Variables

> Template variables exposed by the Text Comment wireframe — read them with velt-data, velt-if, and velt-class to drive dynamic content, conditional rendering, and class toggling.

> [!NOTE]
>
> New to wireframes? Start with [UI Customization Concepts](https://velt.dev/docs/ui-customization/overview.md) and the [Template Variables](https://velt.dev/docs/ui-customization/template-variables.md) overview.

## Overview

The **Text Comment** wireframe powers the small floating toolbar that appears next to selected text. Variables below are available inside any `<velt-text-comment-...-wireframe>` tag via three forms:

| You want to… | Use | Example |
| - | - | - |
| Display a value as text | `<velt-data field="var" />` | `<velt-data field="selectedWordsCount" />` |
| Hide / show conditionally | `velt-if="{var}"` | `velt-if="{showAdder}"` |
| Toggle a CSS class | `velt-class="'cls': {var}"` | `velt-class="'has-words': {selectedWordsCount} > 0"` |

All variables are mapped — reference them by their short name. You do not need the `componentConfig.` prefix.

> [!NOTE]
>
> **Naming conflicts — use full path.** A few names collide with mappings used by Comment Dialog. Inside a Text Comment wireframe, prefer the explicit path on the right when reading these values:
>
> | Conflicting name | Use this in Text Comment |
> | - | - |
> | `user` | `data.user` |
> | `disabled` | `uiState.disabled` |
> | `left` | `uiState.left` |
> | `isPlanExpired` | `uiState.isPlanExpired` |
> | `shadowDom` | `parentLocalUIState.shadowDom` |

## Data State

Per-instance data: the active selection's position, word / character counts, and the current user.

| Variable | Type | Description | Example |
| - | - | - | - |
| `position` | `{ top: number, left: number }` | Absolute position of the floating toolbar relative to the viewport. | `<velt-data field="position.top" />` |
| `position.top` | `number` | Top offset in pixels. | `<velt-data field="position.top" />` |
| `position.left` | `number` | Left offset in pixels. | `<velt-data field="position.left" />` |
| `selectedWordsCount` | `number` | Number of words in the active selection. | `velt-class="'has-words': {selectedWordsCount} > 0"` |
| `selectedCharactersCount` | `number` | Number of characters in the active selection. | `<velt-data field="selectedCharactersCount" />` |
| `allowedElementIds` | `string[]` | Element ids the selection must originate from for the tool to render. | `<velt-data field="allowedElementIds.length" />` |
| `contextId` | `string` \| `null` | Context id linking this tool to a host context. | `<velt-data field="contextId" />` |
| `data.user` | [`User`](https://velt.dev/docs/api-reference/sdk/models/data-models#user) \| `null` | Currently identified end-user. | `<velt-data field="data.user.name" />` |

## UI State

Per-instance UI flags driven by the tool itself.

| Variable | Type | Description | Example |
| - | - | - | - |
| `showAdder` | `boolean` | Floating "add comment" adder is visible for the current selection. | `velt-if="{showAdder}"` |
| `commentToolEnabled` | `boolean` | Comment Tool is enabled at the workspace level. | `velt-class="'tool-on': {commentToolEnabled}"` |
| `isUserAllowed` | `boolean` | Current user has permission to add text comments. | `velt-if="{isUserAllowed}"` |
| `enableTextComments` | `boolean` | Text Comments feature is enabled by config. | `velt-if="{enableTextComments}"` |
| `rewriterEnabled` | `boolean` | AI rewriter feature is enabled. | `velt-if="{rewriterEnabled}"` |
| `rewriterDefaultUIEnabled` | `boolean` | Default rewriter UI should render (instead of a custom one). | `velt-if="{rewriterDefaultUIEnabled}"` |
| `MIN_ALLOWED_WORDS_COUNT` | `number` | Minimum words required before the toolbar shows. | `<velt-data field="MIN_ALLOWED_WORDS_COUNT" />` |
| `MIN_ALLOWED_CHARACTERS_COUNT` | `number` | Minimum characters required before the toolbar shows. | `<velt-data field="MIN_ALLOWED_CHARACTERS_COUNT" />` |
| `MAX_ALLOWED_CHARACTERS_COUNT` | `number` | Maximum characters allowed before the toolbar hides. | `<velt-data field="MAX_ALLOWED_CHARACTERS_COUNT" />` |
| `uiState.disabled` | `boolean` | Tool is disabled by host configuration. | `velt-class="'disabled': {uiState.disabled}"` |
| `uiState.left` | `number` | Horizontal offset of the toolbar (raw value before `position` resolution). | `<velt-data field="uiState.left" />` |
| `uiState.isPlanExpired` | `boolean` | Workspace plan is expired. | `velt-class="'plan-expired': {uiState.isPlanExpired}"` |
| `darkMode` | `boolean` | Dark mode is active. | `velt-class="'dark': {darkMode}"` |
| `variant` | `string` | Per-instance variant tag set on the host element. | `<velt-data field="variant" />` |
| `parentLocalUIState.shadowDom` | `boolean` | Shadow-DOM rendering is enabled for this instance. | *Host config — set via element attribute.* |

> [!NOTE]
>
> **Global config (read-only, internal).** `shadowDom` lives on an internal `globalConfigSignal` not exposed to wireframes — it is reflected onto each primitive's local state, so use `{parentLocalUIState.shadowDom}` to read it.

## Common Props

Every Text Comment primitive accepts:

| React Prop | HTML Attribute | Type | Default | Description |
| - | - | - | - | - |
| `defaultCondition` | `default-condition` | `boolean \| "true" \| "false"` | `true` | When `false`, the component always renders regardless of internal state. |

Signal inputs (for parent-child component composition):

* `[componentConfigSignal]` — shared per-instance config signal (selection position, user, counts, allowed elements).
* `[parentLocalUIState]` — per-instance UI state signal (`darkMode`, `variant`, `shadowDom`).

## Type Reference

Types referenced by the variables above are documented in [Data Models](https://velt.dev/docs/api-reference/sdk/models/data-models.md):

| Type | Description |
| - | - |
| [`User`](https://velt.dev/docs/api-reference/sdk/models/data-models#user) | Identified end-user object. |

## Subcomponents

Each subcomponent below has its own wireframe tag.

### `text-comment-tool` (root)

The root tool that renders next to a text selection.

* **Public element:** `<velt-text-comment-tool>`
* **Wireframe tag:** `<velt-text-comment-tool-wireframe>`

| Property | Value |
| - | - |
| Extra variables | None — root only sees common variables. |
| `shouldShow` | Renders only when an active selection exists inside an allowed element and word / character counts fall within the configured min / max. |

> [tab] React / Next.js
>
> ```jsx theme={null}
> <VeltTextCommentToolWireframe veltClass="'has-words': {selectedWordsCount} > 0">
>   <span><VeltData field="selectedWordsCount" /> words selected</span>
>   <VeltTextCommentToolbarWireframe />
> </VeltTextCommentToolWireframe>
> ```

> [tab] Other Frameworks
>
> ```html theme={null}
> <velt-text-comment-tool-wireframe velt-class="'has-words': {selectedWordsCount} > 0">
>   <span><velt-data field="selectedWordsCount"></velt-data> words selected</span>
>   <velt-text-comment-toolbar-wireframe></velt-text-comment-toolbar-wireframe>
> </velt-text-comment-tool-wireframe>
> ```

***

### `text-comment-toolbar`

The toolbar wrapper that hosts the action buttons.

* **Public element:** `<velt-text-comment-toolbar>`
* **Wireframe tag:** `<velt-text-comment-toolbar-wireframe>`
* **Children (own wireframes):** `*-toolbar-comment-annotation`, `*-toolbar-copywriter`, `*-toolbar-generic`, `*-toolbar-divider`.

| Property | Value |
| - | - |
| Extra variables | None beyond common variables. |

***

### `text-comment-toolbar-comment-annotation`

The "Comment" action button — clicking attaches a new annotation to the selected text.

* **Public element:** `<velt-text-comment-toolbar-comment-annotation>`
* **Wireframe tag:** `<velt-text-comment-toolbar-comment-annotation-wireframe>`

| Property | Value |
| - | - |
| Extra variables | None. |

***

### `text-comment-toolbar-copywriter`

The "AI rewrite" / copywriter action button.

* **Public element:** `<velt-text-comment-toolbar-copywriter>`
* **Wireframe tag:** `<velt-text-comment-toolbar-copywriter-wireframe>`

| Property | Value |
| - | - |
| Extra variables | None. |
| `shouldShow` | `rewriterEnabled === true` |

***

### `text-comment-toolbar-generic`

A generic, customisable action position for an extra button.

* **Public element:** `<velt-text-comment-toolbar-generic>`
* **Wireframe tag:** `<velt-text-comment-toolbar-generic-wireframe>`

| Property | Value |
| - | - |
| Extra variables | None. |

***

### `text-comment-toolbar-divider`

Vertical separator between toolbar items.

* **Public element:** `<velt-text-comment-toolbar-divider>`
* **Wireframe tag:** `<velt-text-comment-toolbar-divider-wireframe>`

| Property | Value |
| - | - |
| Extra variables | None. |

## Deeply-Nested Wireframe Tags

### Text Comment root tag

| Tag | Notes | Example |
| - | - | - |
| `<velt-text-comment-wireframe>` | Outer wireframe — wraps the tool. | (composes the tool) |

## Related

* [Text Comment Primitives](https://velt.dev/docs/ui-customization/features/async/comments/text-comment-primitives.md) — granular components shared across the tool and toolbar.
* [Text Comment Tool Wireframes](https://velt.dev/docs/ui-customization/features/async/comments/text-comment/text-comment-tool/wireframes.md) — composition reference for the tool wireframe.
* [Text Comment Toolbar Wireframes](https://velt.dev/docs/ui-customization/features/async/comments/text-comment/text-comment-toolbar/wireframes.md) — composition reference for the toolbar wireframe.
* [Template Variables](https://velt.dev/docs/ui-customization/template-variables.md) — overview of the `velt-data` / `velt-if` / `velt-class` system.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.