> ## 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](/ui-customization/overview) and the [Template Variables](/ui-customization/template-variables) overview.
</Note>

## 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` |
</Note>

## 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`](/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.
</Note>

## 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](/api-reference/sdk/models/data-models):

| Type                                                 | Description                 |
| ---------------------------------------------------- | --------------------------- |
| [`User`](/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. |

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

  <Tab title="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>
    ```
  </Tab>
</Tabs>

***

### `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](./text-comment-primitives) — granular components shared across the tool and toolbar.
* [Text Comment Tool Wireframes](./text-comment/text-comment-tool/wireframes) — composition reference for the tool wireframe.
* [Text Comment Toolbar Wireframes](./text-comment/text-comment-toolbar/wireframes) — composition reference for the toolbar wireframe.
* [Template Variables](/ui-customization/template-variables) — overview of the `velt-data` / `velt-if` / `velt-class` system.