Custom CSS

Custom CSS is a raw styling escape hatch for the widget, on top of the five built-in Theme controls (Color mode, Corner radius, Elevation, Density, Font). Use it for anything those controls do not cover. This page is the full reference: what your CSS can and cannot do, exactly which selectors are safe to target, and why the rest are blocked.

Quick facts

Field

Project → Settings → Widget → Theme → Custom CSS

Plan required

Pro or above. Same customBranding gate as the custom logo and the Powered-by-Reqio removal toggle. Free always renders the default theme.

Size cap

10,240 bytes (10 KB), measured as UTF-8 byte length. For plain-ASCII CSS this matches the character count shown next to the field; non-ASCII characters count as more than one byte each.

Cascade position

Applied last, inside the widget's own Shadow DOM, after the base token stylesheet and after anything the Theme controls override.

Injection method

Parsed as a stylesheet (CSSStyleSheet.replaceSync + adoptedStyleSheets), never innerHTML. It cannot introduce an element, an event handler, or a script.

Scope

The widget's Shadow DOM only. Nothing in your CSS reaches the rest of your page, and nothing on your page overrides the widget.

Add or edit your CSS

1. 1

   Open the field

   Go to Project → Settings → Widget, scroll to the Theme section, and find Custom CSS near the bottom, below the five segmented controls.

2. 2

   Write your CSS

   Use the selectors and tokens documented below. The field has no live preview for Custom CSS specifically, the widget preview panel reflects it once saved.

3. 3

   Save and verify

   Save the project. Reload a page with the widget embedded and open it. If a rule appears to do nothing, check Troubleshooting before assuming it was silently dropped.

Where your CSS runs

Every widget instance mounts inside a closed-off Shadow DOM. Three layers stack up inside it, in this order:

1. Base tokens and component styles. Written once at mount, as the widget's own constructed stylesheet.
2. Theme control overrides. Any of the five segmented controls that is not Default (or the Primary color field) writes its own CSS variable directly onto the widget's root element as an inline style. Inline styles beat every stylesheet rule for that same property, regardless of load order, see Troubleshooting.
3. Your Custom CSS. Appended after the base stylesheet as its own constructed stylesheet, so it wins ties against layer 1 by normal cascade order. It does not automatically win against layer 2.

What gets rejected, and why

Every save runs through a server-side sanitizer before your CSS is stored, decoding CSS backslash escapes first so an obfuscated form of a blocked construct (for example \75rl( for url() is caught the same as the literal text. A rejected save is not silently truncated, it fails outright and the previous saved value stays in effect.

Everything else is permitted, including arbitrary layout, color, typography, animation, and pseudo-elements. The reject list targets exfiltration and code-execution vectors specifically, not creative freedom inside the widget's own shadow root, which is the accepted and intended use of this field.

Safe selectors and hooks

This is the part to get right. The widget's own component styles are CSS Modules, and the class names they compile to (things like _5y) are machine-generated on every widget.js build. The generator walks every component stylesheet in the whole widget source tree, in sorted order, and assigns each class name a short counted token. Adding, removing, or renaming any component file anywhere in the widget, not just the one you are trying to style, shifts every name that comes after it alphabetically. These names carry no compatibility guarantee and are reassigned on every deploy, whether or not that deploy touched anything visual.

The selectors below are stable because they come from the widget's own JavaScript (attributes and classes it sets deliberately) or from HTML semantics (tag names, ARIA roles) rather than from the CSS Modules build step. Use these.

There is currently no way to target a single specific button, card, or row inside the widget by a stable selector. The widget does not expose ::part() / exportparts or any data-reqio-* styling hook on individual components today, only the container-level and role-level hooks above. If you need to style one exact element and not its siblings, you are limited to the design tokens that element happens to read (which may also be read by other elements) or the blunt tag-name selectors. This is a real, current gap, not something you are missing.

Design tokens available on :host

These are the CSS custom properties the widget's own components read for color, spacing, shape, and type. Overriding one on :host changes it everywhere that token is used. The complete live list can always be read directly from the browser: open devtools, find #reqio-widget-root in the Elements panel, expand its #shadow-root (open) node, and inspect the :host rule in the Styles panel.

Color

Shape, shadow, and spacing

Typography

Worked examples

Recolor a surface, in both modes

A :host(.dark) rule has higher CSS specificity than a plain :host rule (the pseudo-class argument counts like a class), so it always wins for the same property regardless of which stylesheet loads later. Writing only a bare :host { } block for a token that differs between light and dark will apply in light mode but get overridden again by the base stylesheet in dark mode. Write both blocks:

:host {
  --color-bg-raised: #f4f1ea;
  --color-border-subtle: #ded7c6;
}
 
:host(.dark) {
  --color-bg-raised: #1c1a16;
  --color-border-subtle: #322f28;
}

Soften corners and shadows without the Theme control

This only works if the Corner radius and Elevation Theme controls are left on Default. If either is set to something else, that control's inline override wins over this rule, use the control instead for that property.

:host {
  --radius-base: 1.25rem;
  --radius-sm: 0.75rem;
  --shadow-raised: 0 1px 2px rgba(0, 0, 0, 0.08);
}

A second brand color, scoped to just the open panel

--color-brand-primary cannot be overridden at :host (the Primary color field always sets it inline there), but a descendant selector is not fighting that inline style, it is declaring a new value for its own subtree. :host [role="dialog"] matches only the open panel, never the closed launcher bubble, which lives outside it:

:host [role="dialog"] {
  --color-brand-primary: #7c3aed;
}

Native-element fallback

When no container-level hook fits, plain tag selectors still work. They are blunt: this changes every textarea and text input in every flow, not just one.

:host textarea,
:host input[type="text"] {
  font-size: 1rem;
}

Troubleshooting: my rule did nothing

Related