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.

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

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.

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

Recipes & Troubleshooting

Components: Async Collaboration

Components: Realtime Collaboration

Reference

Make your CSS reach Velt

Theme with variables

Dark mode

Fonts

Override classes

Unstyled mode

What CSS can and can’t do

Checklist

​Make your CSS reach Velt

​Theme with variables

​Dark mode

​Fonts

​Override classes

​Unstyled mode

​What CSS can and can’t do

​Checklist

Make your CSS reach Velt

Theme with variables

Dark mode

Fonts

Override classes

Unstyled mode

What CSS can and can’t do

Checklist