Skip to main content

Theming with CSS variables​

Flow renders each form inside a Shadow DOM. The UI uses Mantine components and exposes a set of CSS variables that you can override to match your brand.

There are three ways to customise a form’s theme:

  • Primary colour & custom palettes – in the Form block inspector you can choose a primary colour from Mantine’s palette, define light/dark primary shades and even supply your own colour names and hex values. The plugin will generate 10‑shade palettes from your hex values.

  • Colour mode – set light, dark or auto (system) mode. The current mode is passed into the Shadow DOM via a data‑mantine‑color‑scheme attribute.

  • Theme overrides – the Form block has a Theme Overrides textarea. Any CSS you paste here is injected into the form’s Shadow DOM. This is the place to override Mantine design tokens (--mantine‑…) or Flow‑specific tokens (--flow‑…).

In addition to the wizard tokens, Flow also exposes a generic block token layer for the rest of the form controls. This gives clients a stable override surface for inputs, radios, checkboxes, sliders, ratings, PIN fields, fieldsets, collapse blocks and action buttons.

For the richer display/content blocks, Flow now also exposes dedicated tokens for blockquotes, marks/highlights, badges, code blocks, formatted numbers, spoilers, images and overflow-list items.

Flow Modal and Flow Gallery do not render inside the form shadow root. Override them from ordinary theme/page CSS using .wps-flow-modal and .wps-flow-gallery, not from a form-level Theme Overrides textarea.

Useful light-DOM tokens include:

  • Modal shell: --wps-flow-modal-panel-background, --wps-flow-modal-content-background, --wps-flow-modal-panel-color, --wps-flow-modal-panel-shadow, --wps-flow-modal-backdrop-background
  • Modal chrome: --wps-flow-modal-chrome-background, --wps-flow-modal-chrome-color
  • Gallery: --wps-flow-gallery-stage-background, --wps-flow-gallery-nav-background, --wps-flow-gallery-nav-color, --wps-flow-gallery-meta-color

The modal header/body/actions slot wrappers are intentionally transparent. The shared scrollable surface is .wps-flow-modal__content, so --wps-flow-modal-content-background is the right override when you want one continuous modal backdrop that will not cover sticky header/footer layers or the close button. The top-right chrome wrapper itself stays transparent; --wps-flow-modal-chrome-background and --wps-flow-modal-chrome-color apply to the individual close/fullscreen buttons so those controls remain legible over dark media while still reading as separate actions.

.wps-flow-modal {
  --wps-flow-modal-panel-background: #ffffff;
  --wps-flow-modal-content-background: #ffffff;
  --wps-flow-modal-panel-color: #0f172a;
  --wps-flow-modal-chrome-background: #ffffff;
  --wps-flow-modal-chrome-color: #0f172a;
}

.wps-flow-gallery {
  --wps-flow-gallery-stage-background: #0f172a;
  --wps-flow-gallery-nav-background: rgba(15, 23, 42, 0.82);
  --wps-flow-gallery-nav-color: #ffffff;
  --wps-flow-gallery-meta-color: #e2e8f0;
}

Quick start​

To change fonts, radii and accent colours in all Flow forms on your site, add the following to the Theme Overrides field of your form. You can also define these rules globally in your theme’s CSS using the .smartcloud-flow-shadow-root selector.

/* Target the flow shadow root */
.smartcloud-flow-shadow-root {
  /* Default text styling */
  --mantine-font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
  --mantine-font-size-md: 16px;
  --mantine-line-height-md: 1.6;

  /* Radius and spacing */
  --mantine-radius-md: 6px;
  --mantine-spacing-md: 1rem;

  /* Primary colour */
  --mantine-color-blue-6: #0ea5e9;
  --mantine-primary-color-filled: var(--mantine-color-blue-filled);

  /* Generic Flow fields */
  --flow-control-radius: 999px;
  --flow-control-border-color: var(--mantine-color-blue-3);
  --flow-submit-bg: var(--mantine-color-blue-filled);
  --flow-submit-color: white;
  --flow-fieldset-border: 1px solid var(--mantine-color-blue-2);
}

/* Wizard specific tweaks */
.flow-wizard-container {
  --flow-wizard-gap: 1.5rem;
  --flow-wizard-border-radius: var(--mantine-radius-md);
}

.flow-wizard-title {
  --flow-wizard-title-size: 1.5rem;
  --flow-wizard-title-weight: 700;
}

.flow-wizard-next-button {
  --flow-wizard-next-bg: var(--mantine-color-blue-filled);
  --flow-wizard-next-color: white;
}

.flow-block__pin {
  --flow-pin-input-size: 3rem;
}

.flow-block__collapse {
  --flow-collapse-toggle-radius: 999px;
}

.flow-block__display-blockquote {
  --flow-blockquote-accent: var(--mantine-color-blue-6);
  --flow-blockquote-bg: color-mix(
    in srgb,
    var(--mantine-color-blue-6) 10%,
    white
  );
}

.flow-block__display-badge {
  --flow-badge-padding: 0.4rem 0.85rem;
}

.flow-block__table {
  --flow-table-header-bg: color-mix(in srgb, #0f172a 6%, white);
  --flow-table-border-color: color-mix(in srgb, #0f172a 14%, white);
}

.flow-block__timeline {
  --flow-timeline-accent: var(--mantine-color-blue-6);
}

.flow-block__overflow-list {
  --flow-overflow-item-bg: var(--mantine-color-blue-0);
}

Place this CSS into the Theme Overrides field to see the changes immediately. Use your own colour names and values to align the form with your brand.

Mantine design tokens​

Mantine exposes many CSS variables for spacing, radius, typography, colours, shadows and z‑indices. Flow inherits these variables inside its Shadow DOM. Some useful tokens include:

  • Spacing: --mantine-spacing-xs, --mantine-spacing-sm, --mantine-spacing-md, --mantine-spacing-lg, --mantine-spacing-xl.
  • Radius: --mantine-radius-xs, --mantine-radius-sm, --mantine-radius-md, --mantine-radius-lg, --mantine-radius-xl.
  • Fonts and line heights: --mantine-font-family, --mantine-font-size-sm, --mantine-font-size-md, --mantine-line-height-sm, --mantine-line-height-md.
  • Shadows: --mantine-shadow-xs, --mantine-shadow-sm, --mantine-shadow-md, etc.
  • Colours: --mantine-color-gray-0 … --mantine-color-gray-9, --mantine-color-blue-0 … --mantine-color-blue-9, plus other named colours. When you choose a primary colour the --mantine-primary-color-* variables update automatically.

See the Mantine CSS variables list for a complete reference.

Flow wizard tokens​

Multi‑step forms in Flow use a wizard component. You can customise its layout and colours via --flow‑wizard‑… tokens, scoped on the relevant element. Important tokens include:

  • Container: --flow-wizard-gap (spacing between sections), --flow-wizard-border-radius, --flow-wizard-padding.
  • Header: --flow-wizard-header-spacing, --flow-wizard-title-color, --flow-wizard-title-size, --flow-wizard-title-weight.
  • Progress: --flow-wizard-progress-margin, --flow-wizard-bar-height, --flow-wizard-bar-color, --flow-wizard-bar-bg.
  • Stepper: --flow-wizard-stepper-gap, --flow-wizard-numbers-gap, --flow-wizard-number-size, --flow-wizard-number-active-bg, --flow-wizard-number-inactive-bg, --flow-wizard-number-active-color, --flow-wizard-number-inactive-color.
  • Step content: --flow-wizard-step-gap, --flow-wizard-step-padding, --flow-wizard-step-title-color, --flow-wizard-step-title-size, --flow-wizard-step-title-weight, --flow-wizard-step-desc-color, --flow-wizard-step-desc-size, --flow-wizard-fields-gap.
  • Controls: --flow-wizard-controls-gap, --flow-wizard-controls-margin, --flow-wizard-controls-padding, --flow-wizard-controls-border-top.
  • Buttons: --flow-wizard-prev-color, --flow-wizard-prev-bg, --flow-wizard-prev-border, --flow-wizard-next-color, --flow-wizard-next-bg.

Define these variables in your Theme Overrides CSS to adjust the wizard’s appearance. For example, to enlarge the step numbers and change the active colour:

.flow-wizard-step-number {
  --flow-wizard-number-size: 40px;
  --flow-wizard-number-active-bg: var(--mantine-color-green-6);
  --flow-wizard-number-active-color: white;
}

Flow field tokens​

Regular Flow blocks also expose CSS variables so you can style the non-wizard parts of a form with the same token-based approach.

  • General fields: --flow-field-gap, --flow-field-padding, --flow-field-radius, --flow-field-bg, --flow-field-border, --flow-field-shadow.
  • Labels and messages: --flow-field-label-color, --flow-field-label-size, --flow-field-label-weight, --flow-field-description-color, --flow-field-description-size, --flow-field-error-color, --flow-field-error-size, --flow-field-caption-color, --flow-field-caption-size.
  • Input-like controls: --flow-control-min-height, --flow-control-radius, --flow-control-bg, --flow-control-border-width, --flow-control-border-color, --flow-control-color, --flow-control-placeholder-color, --flow-control-padding-inline, --flow-control-padding-block, --flow-control-focus-border-color, --flow-control-focus-shadow, --flow-control-disabled-opacity.
  • Choice controls: --flow-choice-size, --flow-choice-color, --flow-choice-label-color.
  • Sliders: --flow-slider-track-size, --flow-slider-track-bg, --flow-slider-bar-color, --flow-slider-thumb-size, --flow-slider-thumb-bg, --flow-slider-thumb-border.
  • PIN and rating: --flow-pin-gap, --flow-pin-input-size, --flow-rating-size, --flow-rating-active-color, --flow-rating-inactive-color.
  • Fieldsets and collapse: --flow-fieldset-border, --flow-fieldset-radius, --flow-fieldset-padding, --flow-fieldset-legend-color, --flow-collapse-toggle-bg, --flow-collapse-toggle-border, --flow-collapse-toggle-radius, --flow-collapse-toggle-padding, --flow-collapse-toggle-color.
  • Action buttons: --flow-action-button-radius, --flow-action-button-padding, --flow-submit-bg, --flow-submit-color, --flow-submit-border, --flow-save-draft-bg, --flow-save-draft-color, --flow-save-draft-border.
  • Display / content blocks: --flow-display-text-color, --flow-display-text-weight, --flow-display-text-line-height, --flow-display-title-color, --flow-display-title-weight, --flow-display-title-line-height, --flow-display-title-letter-spacing, --flow-blockquote-bg, --flow-blockquote-accent, --flow-blockquote-color, --flow-blockquote-radius, --flow-blockquote-padding, --flow-blockquote-gap, --flow-blockquote-border-width, --flow-blockquote-icon-size, --flow-blockquote-text-style, --flow-blockquote-cite-color, --flow-blockquote-cite-size, --flow-mark-bg, --flow-mark-color, --flow-mark-radius, --flow-mark-padding, --flow-highlight-bg, --flow-highlight-color, --flow-highlight-radius, --flow-highlight-padding, --flow-badge-padding, --flow-badge-circle-padding, --flow-badge-font-size, --flow-badge-font-weight, --flow-badge-letter-spacing, --flow-badge-text-transform, --flow-code-inline-bg, --flow-code-inline-color, --flow-code-block-bg, --flow-code-block-color, --flow-code-radius, --flow-code-padding, --flow-code-block-padding, --flow-number-color, --flow-number-weight, --flow-number-font-variant, --flow-spoiler-toggle-color, --flow-spoiler-content-color, --flow-image-radius, --flow-image-caption-color, --flow-image-caption-size, --flow-list-color, --flow-list-marker-color, --flow-list-padding-start, --flow-list-item-gap, --flow-table-color, --flow-table-border-color, --flow-table-cell-border-color, --flow-table-striped-bg, --flow-table-header-bg, --flow-table-header-color, --flow-table-header-weight, --flow-table-cell-color, --flow-table-caption-color, --flow-table-caption-padding-bottom, --flow-table-cell-padding-inline, --flow-table-cell-padding-block, --flow-timeline-color, --flow-timeline-gap, --flow-timeline-item-gap, --flow-timeline-content-gap, --flow-timeline-accent, --flow-timeline-line-opacity, --flow-timeline-bullet-color, --flow-timeline-bullet-weight, --flow-timeline-title-color, --flow-timeline-title-weight, --flow-overflow-item-bg, --flow-overflow-item-border, --flow-overflow-item-color, --flow-overflow-item-gap, --flow-overflow-item-radius, --flow-overflow-item-padding, --flow-overflow-item-shadow, --flow-overflow-summary-cursor, --flow-overflow-summary-font-weight, --flow-overflow-summary-letter-spacing.
  • AI suggestions: --flow-ai-suggestions-border-thickness, --flow-ai-suggestions-border-stops, --flow-ai-suggestions-border-speed.
  • Submission metadata / success-state helpers: --flow-submission-meta-bg, --flow-submission-meta-border, --flow-submission-meta-radius, --flow-submission-meta-padding, --flow-submission-meta-gap, --flow-submission-meta-label-color, --flow-submission-meta-value-color, --flow-submission-meta-value-font, --flow-submission-meta-copy-bg, --flow-submission-meta-copy-border, --flow-submission-meta-copy-color, --flow-submission-meta-shadow.

These tokens act as theme defaults. If a block explicitly sets colour, radius or similar props in the editor, that per-block setting may still take precedence over the token.

If you want to scope overrides to a specific block type, Flow adds stable classes around each runtime block:

  • Input-like blocks: .flow-block__text, .flow-block__textarea, .flow-block__select, .flow-block__number, .flow-block__password, .flow-block__date
  • Choice blocks: .flow-block__checkbox, .flow-block__radio, .flow-block__switch
  • Other fields: .flow-block__pin, .flow-block__slider, .flow-block__rangeslider, .flow-block__rating, .flow-block__file, .flow-block__tags
  • Containers and actions: .flow-block__fieldset, .flow-block__collapse, .flow-block__submit, .flow-block__save-draft
  • Display/content blocks: .flow-block__display-text, .flow-block__display-title, .flow-block__display-blockquote, .flow-block__display-mark, .flow-block__display-highlight, .flow-block__display-badge, .flow-block__display-code, .flow-block__display-number-formatter, .flow-block__display-spoiler, .flow-block__display-image, .flow-block__list, .flow-block__list-item, .flow-block__table, .flow-block__table-row, .flow-block__table-th, .flow-block__table-td, .flow-block__timeline, .flow-block__timeline-item, .flow-block__overflow-list, .flow-block__overflow-list-item
  • AI and response surfaces: .flow-ai-suggestions, .flow-ai-suggestions-border, .flow-submission-meta

These .flow-block__* wrappers are the stable theming surface. The interactive Mantine control or button often lives one level deeper and consumes the --flow-* token there, so prefer setting tokens on the wrapper instead of targeting internal helper classes.

Success-state layouts reuse the action-button and submission-meta styling surfaces, so most confirmation-screen theming can be handled through the action button tokens and .flow-submission-meta overrides instead of separate success-state-only variables.

For example, to give only the submit button and PIN fields a stronger brand style:

.flow-block__submit {
  --flow-submit-bg: var(--mantine-color-green-6);
  --flow-submit-color: white;
}

.flow-block__pin {
  --flow-pin-input-size: 3rem;
  --flow-control-radius: 12px;
}

Copy-paste theme recipes​

These presets are meant as a starting point for client projects. Paste any of them into the Theme Overrides field, then adjust the colours and spacing tokens as needed.

Rounded SaaS​

Use this when you want a soft, modern app-like look with rounded controls and a stronger primary action.

.smartcloud-flow-shadow-root {
  --mantine-font-family: Inter, system-ui, sans-serif;
  --mantine-radius-md: 14px;
  --mantine-spacing-md: 1rem;
  --mantine-color-blue-6: #2563eb;
  --mantine-primary-color-filled: var(--mantine-color-blue-filled);

  --flow-control-radius: 14px;
  --flow-control-border-color: var(--mantine-color-blue-2);
  --flow-control-focus-border-color: var(--mantine-color-blue-5);
  --flow-control-focus-shadow: 0 0 0 3px rgb(37 99 235 / 0.12);

  --flow-submit-bg: linear-gradient(135deg, #2563eb, #1d4ed8);
  --flow-submit-color: white;
  --flow-action-button-radius: 14px;

  --flow-wizard-number-active-bg: #2563eb;
  --flow-wizard-next-bg: linear-gradient(135deg, #2563eb, #1d4ed8);
}

Clinical Minimal​

Use this for healthcare, legal or administrative forms where clarity matters more than brand expression.

.smartcloud-flow-shadow-root {
  --mantine-font-family: system-ui, sans-serif;
  --mantine-radius-md: 6px;
  --mantine-spacing-md: 0.875rem;

  --flow-field-gap: 0.375rem;
  --flow-control-radius: 6px;
  --flow-control-bg: #ffffff;
  --flow-control-border-color: #cbd5e1;
  --flow-control-focus-border-color: #0f172a;
  --flow-control-focus-shadow: 0 0 0 1px #0f172a;

  --flow-field-description-color: #475569;
  --flow-field-error-color: #b91c1c;

  --flow-fieldset-border: 1px solid #cbd5e1;
  --flow-collapse-toggle-border: 1px solid #cbd5e1;

  --flow-submit-bg: #0f172a;
  --flow-submit-color: #ffffff;
  --flow-save-draft-border: 1px solid #cbd5e1;
}

Bold Brand​

Use this when the form should visibly carry the client brand instead of blending into the page chrome.

.smartcloud-flow-shadow-root {
  --mantine-font-family: "Space Grotesk", system-ui, sans-serif;
  --mantine-radius-md: 10px;
  --mantine-color-pink-6: #e11d48;
  --mantine-primary-color-filled: var(--mantine-color-pink-filled);

  --flow-control-radius: 10px;
  --flow-control-border-width: 2px;
  --flow-control-border-color: #fecdd3;
  --flow-control-focus-border-color: #e11d48;
  --flow-control-focus-shadow: 0 0 0 3px rgb(225 29 72 / 0.18);

  --flow-choice-color: #e11d48;
  --flow-slider-bar-color: #e11d48;
  --flow-slider-thumb-border: 2px solid #e11d48;
  --flow-rating-active-color: #e11d48;

  --flow-submit-bg: #e11d48;
  --flow-submit-color: #ffffff;

  --flow-wizard-number-active-bg: #e11d48;
  --flow-wizard-next-bg: #e11d48;
}

Dark Contrast​

Use this when the form sits inside a dark layout and needs stronger contrast without manually restyling every component.

.smartcloud-flow-shadow-root[data-mantine-color-scheme="dark"] {
  --mantine-color-body: #0f172a;
  --mantine-color-text: #e5e7eb;

  --flow-field-description-color: #94a3b8;
  --flow-control-bg: #111827;
  --flow-control-color: #f8fafc;
  --flow-control-border-color: #334155;
  --flow-control-placeholder-color: #64748b;
  --flow-control-focus-border-color: #38bdf8;
  --flow-control-focus-shadow: 0 0 0 3px rgb(56 189 248 / 0.18);

  --flow-fieldset-border: 1px solid #334155;
  --flow-collapse-toggle-bg: #111827;
  --flow-collapse-toggle-border: 1px solid #334155;

  --flow-submit-bg: #38bdf8;
  --flow-submit-color: #0f172a;
  --flow-save-draft-color: #e5e7eb;
  --flow-save-draft-border: 1px solid #475569;

  --flow-wizard-bar-bg: #334155;
  --flow-wizard-number-inactive-bg: #1e293b;
  --flow-wizard-number-inactive-color: #cbd5e1;
  --flow-wizard-next-bg: #38bdf8;
  --flow-wizard-next-color: #0f172a;
}

Best practices​

  • Keep your Theme Overrides scoped to .smartcloud-flow-shadow-root so they only affect Flow UIs.
  • Use Mantine variables to ensure colours and spacing remain consistent across light and dark modes.
  • When defining custom colours via the Form block’s Colours field, pick unique names (for example brand) and use them in your overrides (--mantine-color-brand-6).
  • Test your overrides in both light and dark modes. Use the data-mantine-color-scheme attribute on .smartcloud-flow-shadow-root to set or detect the mode.