Setup

Set up your project for UI customization: install Velt, make sure your CSS can reach it, and organize your customization code.

Install Velt

Customization starts from a working Velt installation: SDK installed, user authenticated, document set, and Velt’s default UI (comments, sidebar, …) rendering in your app.Not there yet? Follow the Quickstart (or use the Installation Plugin), then come back.

Get Velt’s default UI showing first, unstyled. Confirm comments work. Then customize. If you build custom UI against a Velt that isn’t initialized, you can’t tell setup bugs from styling bugs.

Recommended: use the UI Customization Plugin

If your design is in Figma and you use Cursor or Claude Code, install the UI Customization Plugin: it picks the approach, builds the customization in your app, and verifies the result against your design in a real browser (comments and notifications today).If your design isn’t in Figma, or you prefer building by hand, continue with the manual steps below.

Choose your shadow DOM strategy

Velt can render inside a shadow DOM (an isolated DOM bubble). That isolation blocks your stylesheets, so decide up front how your CSS reaches Velt:

Variable-only theming (you only override --velt-* tokens): works regardless of shadow DOM; variables cross the boundary. Nothing to change.
Selector-based CSS (class/element selectors) or styled wireframes: these cannot reach inside the shadow DOM. Pick one of two supported options:

Option A: turn shadow DOM off so your normal stylesheet reaches the elements:

React / Next.js
Other Frameworks

<VeltComments shadowDom={false} />
<VeltCommentsSidebar shadowDom={false} />

<velt-comments shadow-dom="false"></velt-comments>
<velt-comments-sidebar shadow-dom="false"></velt-comments-sidebar>

Option B: keep shadow DOM on and inject your CSS into the shadow root (keeps Velt’s style isolation):

React / Next.js
Other Frameworks

const { client } = useVeltClient();
client.injectCustomCss({ type: "styles", value: ".velt-comment-dialog-composer{border-radius:10px !important}" });

Velt.injectCustomCss({ type: "styles", value: ".velt-comment-dialog-composer{border-radius:10px !important}" });

If you do neither, your --velt-* overrides still apply but your class-based CSS won’t reach inside, so it looks like “my CSS does nothing.”Rule of thumb: anything beyond pure variable theming ⇒ shadow DOM off or injectCustomCss. (Details: CSS.)

Set up the folder structure

This structure keeps your app code, Velt setup, and Velt UI customization cleanly separated. Use it as-is.

components/
├── Header.tsx, Body.tsx, …          ← your normal app UI (no Velt customization here)
└── velt/                            ← ALL Velt-related code lives here
    ├── VeltCollaboration.tsx        Mounts Velt components + global config
    ├── VeltInitializeUser.tsx       Identify the user
    ├── VeltInitializeDocument.tsx   Set the document(s)
    └── ui-customization/            ← ALL customization lives here
        ├── VeltCustomization.tsx    The single <VeltWireframe> root (if wireframing)
        ├── VeltCommentDialogWf.tsx  One file per customized surface
        ├── VeltCommentSidebarWf.tsx
        ├── ThreadCardWf.tsx
        └── styles.css               ONE stylesheet for all Velt CSS

Why this works:

One place to look. Anyone (or any tool) finds all customization under components/velt/ui-customization/.
App UI stays separate from Velt UI: no tangling.
One stylesheet for all Velt CSS variables/classes, not scattered across components.
One <VeltWireframe> root (in VeltCustomization.tsx): easy to find.

Keep exactly one <VeltWireframe> in the whole app. It feeds a global registry; extra roots merge first-with-content-wins, which is order-dependent and conflict-prone. VeltCustomization.tsx is its one home.

For CSS-only or primitives-only customization you may not need a ui-customization/ folder at all: a single velt.css + the components in VeltCollaboration.tsx is enough. Adopt the full structure when you start wireframing.

Build your customization

Open the page for your chosen approach: CSS, Wireframes, Primitives, or Headless. Mixing layers on one surface? See Combining approaches.

As you build, handle accessibility, i18n, RTL, responsive behavior, and testing alongside each surface, not at the end: see Cross-cutting concerns.

Concepts

Approaches

Recipes & Troubleshooting

Components: Async Collaboration

Components: Realtime Collaboration

Reference

Install Velt

Recommended: use the UI Customization Plugin

Choose your shadow DOM strategy

Set up the folder structure

Build your customization