CSS

Change Velt’s look (colors, spacing, fonts, radius, shadows) without touching its structure or behavior. It’s the lowest-effort approach, and it layers on top of every other one.

Two shortcuts before you write any CSS: build a theme visually in the Theme Playground, or have the UI Customization Plugin extract the values from your Figma design and write the overrides for you.

className and style props on Velt components do nothing. Style Velt with the variables and classes below, or add classes to your own markup inside a wireframe.

Make your CSS reach Velt

Velt can render inside a shadow DOM, which blocks your stylesheets.

CSS variables (--velt-*) always cross the boundary. Theming with variables alone needs nothing here.
Class and element selectors don’t. Pick one of these:

Option A: turn shadow DOM off.

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 it on and inject your CSS into the shadow root. Use type: "styles" for a CSS string, type: "link" for a stylesheet URL.

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; }
` });

Wireframes change this. Registering a component’s root wireframe (e.g. VeltCommentDialogWireframe) removes that component’s shadow DOM automatically, so your class CSS reaches it. A nested-only wireframe doesn’t: set shadowDom={false} yourself. Inline style="" always works either way.Not every component takes shadowDom: the per-component prop lists are in Props.

Theme with variables

Put all Velt CSS in one stylesheet and override the tokens you need:

/* velt.css */
:root {
  --velt-light-mode-accent: #FF6B35;
  --velt-light-mode-accent-hover: #E55A29;
  --velt-light-mode-background-0: #FFFFFF;
  --velt-light-mode-text-0: #0A0A0A;

  --velt-border-radius-md: 10px;
  --velt-spacing-md: 14px;
  --velt-font-size-sm: 13px;
}

Every token is listed in CSS variables; don’t invent names. Older surfaces read a few --legacy-velt-* tokens, which are listed there too.

Rather than hand-picking values, build your theme in the Theme Playground: adjust colors, radius, spacing, and typography against a live preview, then copy the generated variables straight into this stylesheet.

Dark mode

Velt sets data-velt-theme="dark" on the document root when dark mode is on. You supply the values:

:root[data-velt-theme="dark"] {
  --velt-dark-mode-accent: #FF8A5C;
  --velt-dark-mode-background-0: #0F0F0F;
  --velt-dark-mode-text-0: #FFFFFF;
}

Turn it on with the darkMode prop (also dialogDarkMode, pinDarkMode, … for components Velt injects for you), with setDarkMode() app-wide, or by wiring your own prefers-color-scheme listener to it:

React / Next.js
Other Frameworks

// Global
const { client } = useVeltClient();
client.setDarkMode(true);

// Per component
<VeltComments darkMode={true} dialogDarkMode={true} pinDarkMode={true} />

<script>
  Velt.setDarkMode(true);
</script>

<velt-comments dark-mode="true" dialog-dark-mode="true" pin-dark-mode="true"></velt-comments>

Fonts

One global token sets the font across every Velt surface:

:root {
  --velt-default-font-family: "Inter", "Helvetica Neue", Arial, sans-serif;
}

Font sizes use the --velt-font-size-* scale. Line-height and weight are per-component.

Override classes

For anything variables don’t cover, target Velt’s classes. Velt’s own styles are high-specificity, so your overrides need !important. That’s the supported way to do class-based Velt CSS, not a hack.

Run with shadowDom={false} and inspect the element.
Prefer its velt-* BEM class over the short legacy twin: velt-comment-dialog--selected, not selected.
Write the rule with !important:

.velt-composer--submit-button {
  background: #3d5afe !important;
  border-radius: 6px !important;
}

CSS classes lists every structural and stateful class (unread, resolved, selected, hover, filter-applied, …). Class names can shift between versions, so prefer a --velt-* variable where one exists and re-check overrides on upgrade.

Unstyled mode

Restyling most of the UI anyway? Strip Velt’s visual styling with setUnstyledMode() (v6.0.0-beta.10+) and bring your own CSS. Layout and positioning styles are kept so components stay functional. It covers styles in the page head and inside shadow roots, and is reversible.

React / Next.js
Other Frameworks

const { client } = useVeltClient();

client.setUnstyledMode(true);                                    // keep layout styles
client.setUnstyledMode(true, { keepFunctionalStyles: false });   // strip everything
client.setUnstyledMode(false);                                   // restore

Velt.setUnstyledMode(true);
Velt.setUnstyledMode(true, { keepFunctionalStyles: false });
Velt.setUnstyledMode(false);

To also drop Velt’s global styles (the ones outside its own components), set globalStyles: false in your config:

React / Next.js
Other Frameworks

<VeltProvider apiKey='API_KEY' config={{ globalStyles: false }}>
    {/* Your app content */}
</VeltProvider>

Velt.initConfig('API_KEY', { globalStyles: false });

Recipes

Specific selector tricks for things variables don’t reach. All of these assume shadowDom={false} and use !important for the reason above.

Map your brand tokens onto Velt's

Define your brand once as your own variables, then point the --velt-* tokens at them. One place to change your brand, and Velt stays in sync with your app.

:root {
  --brand-accent: #FF6B35;
  --velt-light-mode-accent: var(--brand-accent);
  --velt-light-mode-accent-hover: color-mix(in srgb, var(--brand-accent) 85%, black);
}

Reveal actions only on hover

Hide the kebab, options, and reaction icons until hover. Velt already wires this on .velt-thread-card--container:hover, and you can force it with .velt-thread-card--show-actions.

.hw-comment-actions { opacity: 0; transition: opacity .12s ease; }
.hw-comment:hover .hw-comment-actions,
.hw-comment-actions:focus-within { opacity: 1; }

There is no hover on touch devices. Velt force-shows per-comment actions at mobile widths, so if you build your own hover-reveal add an always-visible fallback under a mobile media query.

Swap the reaction tool and reaction panel by count

The pin carries velt-reaction-pin--no-reactions only when the count is 0. Use it, and :has(app-reaction-pin), to position or swap the reaction UI.

.velt-thread-card--reactions:not(:has(app-reaction-pin)) { display: none !important; }

Style the unread dot

.velt-thread-card--name--unread {
  width:6px !important; height:6px !important; border-radius:50% !important;
  background: var(--brand) !important; margin-left:0 !important;
}

Style resolved threads

There is no --resolved class. Detect the unresolve button instead.

.velt-comment-dialog--sidebar-mode:has(velt-comment-dialog-unresolve-button-internal .icon)
  .velt-thread-card--message { color: var(--muted) !important; }

Hide a container when its data slot is empty

.context-row:has(app-data:empty) { display:none !important; }
app-if:empty { display:none !important; }   /* unwrap empty conditionals */

Resize the default avatar

snippyly-user-avatar {
  --legacy-velt-user-avatar-height:20px !important;
  --legacy-velt-user-avatar-width:20px !important;
}

Indent threaded replies

app-comment-dialog-threads > :not(:first-child) { padding-left: 26px; }

velt-comment-dialog-options-dropdown-content-internal,
div:has(> velt-comment-dialog-options-dropdown-content-internal) {
  background:transparent !important; box-shadow:none !important;
  border:none !important; padding:0 !important; width:max-content !important;
}

Remove default styling a wireframe didn't replace

Wireframing a slot doesn’t strip all of Velt’s surrounding defaults: borders, padding, backgrounds, fixed widths, and popover chrome often remain. Inspect, find the velt-* class, override it.

.velt-status-dropdown--content {
  border:none !important; background:transparent !important;
  box-shadow:none !important; padding:0 !important;
}

Treat “inspect, find class, override” as part of every wireframe pass, not a failure.

Switch a collapsed composer to expanded

Render a collapsed input and an expanded one in the composer slot, and let Velt’s state classes switch between them.

.velt-composer-open .composer-collapsed { display:none !important; }
.velt-composer-open .composer-expanded  { display:flex !important; }

The switches are velt-composer-open, velt-comment-dialog--no-comments, and velt-composer-edit-mode.

Make a sidebar or list take the available height and scroll

The tricky one. Velt’s own internal container elements keep their default styles and sit between your layout and the scrollable list. If any link in that flex chain lacks min-height:0, flex:1, or height:100%, the list grows past the panel and scrolling silently breaks. Inspect the Velt internal element and force the chain.

.my-panel { display:flex; flex-direction:column; height:100%; min-height:0; }
/* Velt's internal panel element: the hidden link you find by inspecting */
.my-panel > app-comment-sidebar-panel { display:flex; flex-direction:column; flex:1 1 auto; min-height:0; }
.my-list-body { flex:1; min-height:0; overflow-y:auto; }
/* sometimes Velt's own list viewport needs forcing too: */
velt-comments-sidebar /* …inspect for the exact internal el… */ { height:100% !important; min-height:0 !important; overflow-y:auto !important; }

min-height:0 (plus flex:1 or height:100%) must hold on every element from your wrapper down to the scroll container, including Velt’s internal ones. One missing link kills the scroll, so re-test that scrolling actually works.

Fix a dialog or pin rendering in the wrong place

Some Velt pieces (dialogs, pins, overlays, reaction pins) render with position: absolute. If a mounted primitive or wireframe appears top-left or escaping its box, give its parent position: relative so the absolute child anchors to it.

.my-comment-dialog-host { position: relative; }

The most common “why is my dialog floating in the wrong spot?” fix.

What CSS can and can’t do

✅ CSS can	❌ CSS cannot
Recolor everything (light + dark)	Reorder or restructure the UI
Change spacing, radius, fonts, shadows	Add or remove UI parts (use a prop or wireframe)
Theme to match a brand	Insert your own markup between Velt’s pieces
Adjust z-index layering	Change behavior

Writing display:none to remove parts, or wishing you could move a button? You’ve hit CSS’s ceiling: escalate to wireframes to restructure, or primitives to toggle features.

Troubleshooting

Common CSS symptoms, in Debugging:

Checklist

shadowDom={false} on components you style with classes.
All Velt CSS in one stylesheet.
Only token names that exist in CSS variables.
Dark values under :root[data-velt-theme="dark"].
No display:none to remove features: toggle them with a prop.

Concepts

Approaches

Components: Async Collaboration

Components: Realtime Collaboration

Reference

Make your CSS reach Velt

Theme with variables

Dark mode

Fonts

Override classes

Unstyled mode

Recipes

What CSS can and can’t do

Troubleshooting

Checklist

​Make your CSS reach Velt

​Theme with variables

​Dark mode

​Fonts

​Override classes

​Unstyled mode

​Recipes

​What CSS can and can’t do

​Troubleshooting

​Checklist

Make your CSS reach Velt

Theme with variables

Dark mode

Fonts

Override classes

Unstyled mode

Recipes

What CSS can and can’t do

Troubleshooting

Checklist