Custom themes

Full createTheme() API reference and CSS variable catalog. Start with the theming overview if you’re new to theming.

`createTheme()` options

import { createTheme } from 'superdoc';

const theme = createTheme({
  name: 'my-brand',
  font: 'Inter, sans-serif',
  radius: '8px',
  shadow: '0 2px 8px rgba(0,0,0,0.1)',
  colors: {
    action: '#6366f1',        // buttons, links, active states
    actionHover: '#4f46e5',
    actionText: '#ffffff',    // text on action buttons
    bg: '#ffffff',             // panels, cards, dropdowns
    hoverBg: '#f1f5f9',       // hover backgrounds
    activeBg: '#e2e8f0',      // active/pressed backgrounds
    disabledBg: '#f5f5f5',
    text: '#1e293b',           // primary text
    textMuted: '#64748b',      // secondary text
    textDisabled: '#94a3b8',
    border: '#e2e8f0',
  },
  // Escape hatch: any --sd-* CSS variable
  vars: {
    '--sd-ui-toolbar-bg': '#f8fafc',
    '--sd-ui-comments-card-bg': '#f0f0ff',
  },
});

document.documentElement.classList.add(theme);

Start with colors only. Use vars when a specific component needs to look different.

Dark theme example

import { createTheme } from 'superdoc';

const dark = createTheme({
  name: 'dark',
  colors: {
    bg: '#1a1a2e',
    hoverBg: '#2a2a3e',
    activeBg: '#3a3a4e',
    text: '#e2e8f0',
    textMuted: '#94a3b8',
    border: '#334155',
    action: '#60a5fa',
    actionHover: '#93c5fd',
    actionText: '#0f172a',
  },
  vars: {
    '--sd-ui-toolbar-bg': '#0f172a',
    '--sd-ui-toolbar-button-text': '#e2e8f0',
    '--sd-ui-comments-card-bg': '#1e293b',
    '--sd-ui-comments-body-text': '#cbd5e1',
  },
});

document.documentElement.classList.add(dark);

Raw CSS alternative

You can also write CSS directly. Apply overrides to <html>.

.dark-theme {
  --sd-ui-bg: #1a1a2e;
  --sd-ui-hover-bg: #2a2a3e;
  --sd-ui-active-bg: #3a3a4e;
  --sd-ui-text: #e2e8f0;
  --sd-ui-text-muted: #94a3b8;
  --sd-ui-border: #334155;
  --sd-ui-action: #60a5fa;
  --sd-ui-action-hover: #93c5fd;
  --sd-ui-action-text: #0f172a;

  /* Toolbar */
  --sd-ui-toolbar-bg: #0f172a;
  --sd-ui-toolbar-button-text: #e2e8f0;
  --sd-ui-toolbar-button-hover-bg: #1e293b;
  --sd-ui-toolbar-button-active-bg: #334155;

  /* Dropdowns */
  --sd-ui-dropdown-bg: #1e293b;
  --sd-ui-dropdown-border: #334155;
  --sd-ui-dropdown-hover-bg: #2d3a4e;

  /* Comments */
  --sd-ui-comments-card-bg: #1e293b;
  --sd-ui-comments-card-active-bg: #0f172a;
  --sd-ui-comments-input-bg: #1e293b;
  --sd-ui-comments-author-text: #e2e8f0;
  --sd-ui-comments-body-text: #cbd5e1;
  --sd-ui-comments-timestamp-text: #64748b;
}

Variable reference

Semantic (UI-wide)

These cascade to every component. Changing one updates the entire UI.

Variable	Default	Controls
`--sd-ui-font-family`	`Arial, Helvetica, sans-serif`	UI font
`--sd-ui-text`	`#47484a`	Primary text
`--sd-ui-text-muted`	`#666666`	Secondary text
`--sd-ui-text-disabled`	`#ababab`	Disabled text
`--sd-ui-bg`	`#ffffff`	Default background
`--sd-ui-hover-bg`	`#dbdbdb`	Hover background
`--sd-ui-active-bg`	`#c8d0d8`	Active/pressed background
`--sd-ui-disabled-bg`	`#f5f5f5`	Disabled background
`--sd-ui-border`	`#dbdbdb`	Default border
`--sd-ui-action`	`#1355ff`	Action/accent color
`--sd-ui-action-hover`	`#0f44cc`	Action hover
`--sd-ui-action-text`	`#ffffff`	Text on action buttons
`--sd-ui-shadow`	`0 4px 12px rgba(0,0,0,0.12)`	Default shadow
`--sd-ui-radius`	`6px`	Default border radius

Variable	Default	Controls
`--sd-ui-toolbar-height`	`32px`	Row height
`--sd-ui-toolbar-padding-x`	`16px`	Horizontal padding
`--sd-ui-toolbar-padding-y`	`4px`	Vertical padding
`--sd-ui-toolbar-item-gap`	`2px`	Gap between buttons
`--sd-ui-toolbar-item-padding`	`5px`	Button padding
`--sd-ui-toolbar-bg`	`transparent`	Background
`--sd-ui-toolbar-button-text`	inherits `--sd-ui-text`	Button text/icon color
`--sd-ui-toolbar-button-hover-bg`	inherits `--sd-ui-hover-bg`	Button hover
`--sd-ui-toolbar-button-active-bg`	inherits `--sd-ui-active-bg`	Button active

Dropdowns

Toolbar dropdowns (font picker, style picker) and the overflow menu.

Variable	Default	Controls
`--sd-ui-dropdown-bg`	inherits `--sd-ui-bg`	Panel background
`--sd-ui-dropdown-border`	inherits `--sd-ui-border`	Panel border
`--sd-ui-dropdown-text`	inherits `--sd-ui-text`	Option text
`--sd-ui-dropdown-hover-text`	inherits dropdown text	Hovered option text
`--sd-ui-dropdown-selected-text`	inherits dropdown text	Selected option text
`--sd-ui-dropdown-hover-bg`	inherits `--sd-ui-hover-bg`	Option hover
`--sd-ui-dropdown-active-bg`	inherits `--sd-ui-active-bg`	Option active
`--sd-ui-dropdown-option-radius`	`3px`	Option border radius
`--sd-ui-dropdown-shadow`	`0 8px 24px rgba(0,0,0,0.16)`	Panel shadow

The right-click menu.

Variable	Default	Controls
`--sd-ui-menu-bg`	inherits `--sd-ui-bg`	Background
`--sd-ui-menu-text`	inherits `--sd-ui-text`	Text
`--sd-ui-menu-font-size`	`12px`	Text size
`--sd-ui-menu-radius`	`0`	Border radius
`--sd-ui-menu-border`	inherits `--sd-ui-border`	Border
`--sd-ui-menu-shadow`	`0 0 0 1px rgba(0,0,0,0.05), 0 10px 20px rgba(0,0,0,0.1)`	Shadow
`--sd-ui-menu-input-border`	inherits `--sd-ui-border`	Search input border
`--sd-ui-menu-input-focus-border`	inherits `--sd-ui-action`	Search input focus
`--sd-ui-menu-item-hover-bg`	inherits `--sd-ui-hover-bg`	Item hover
`--sd-ui-menu-item-active-bg`	inherits `--sd-ui-active-bg`	Active item
`--sd-ui-menu-item-active-text`	inherits `--sd-ui-action`	Active item text

Variable	Default	Controls
`--sd-ui-tooltip-bg`	`#262626`	Background (intentionally dark)
`--sd-ui-tooltip-text`	`#ffffff`	Text (intentionally light)
`--sd-ui-tooltip-radius`	`6px`	Border radius
`--sd-ui-tooltip-shadow`	`0 3px 12px rgba(0,0,0,0.28)`	Shadow

Comments

Card styling, typography, and input elements for the comments sidebar. Card:

Variable	Default	Controls
`--sd-ui-comments-card-bg`	`#f3f6fd`	Default card
`--sd-ui-comments-card-hover-bg`	inherits card bg	Hovered card
`--sd-ui-comments-card-active-bg`	inherits `--sd-ui-bg`	Selected card
`--sd-ui-comments-card-resolved-bg`	inherits `--sd-ui-disabled-bg`	Resolved card
`--sd-ui-comments-card-active-border`	inherits `--sd-ui-border`	Selected card border
`--sd-ui-comments-card-radius`	`12px`	Card radius
`--sd-ui-comments-card-padding`	`16px`	Card padding
`--sd-ui-comments-card-shadow`	`0 4px 12px rgba(50,50,50,0.15)`	Card shadow
`--sd-ui-comments-transition`	`all 200ms ease`	Animation
`--sd-ui-comments-separator`	inherits `--sd-ui-border`	Divider line

Text:

Variable	Default	Controls
`--sd-ui-comments-author-text`	inherits `--sd-ui-text`	Author name
`--sd-ui-comments-author-size`	`14px`	Author size
`--sd-ui-comments-author-weight`	`600`	Author weight
`--sd-ui-comments-timestamp-text`	inherits `--sd-ui-text-muted`	Timestamp
`--sd-ui-comments-timestamp-size`	`12px`	Timestamp size
`--sd-ui-comments-body-text`	inherits `--sd-ui-text`	Body text
`--sd-ui-comments-body-size`	`14px`	Body size

Input:

Variable	Default	Controls
`--sd-ui-comments-input-bg`	inherits `--sd-ui-bg`	Input background
`--sd-ui-comments-input-border`	inherits `--sd-ui-border`	Input border

Status:

Variable	Default	Controls
`--sd-ui-comments-resolved-text`	`#00853d`	”Resolved” badge
`--sd-ui-comments-insert-text`	`#00853d`	Tracked change insert
`--sd-ui-comments-delete-text`	`#cb0e47`	Tracked change delete

Filter dropdown:

Variable	Default	Controls
`--sd-ui-comments-dropdown-bg`	inherits `--sd-ui-bg`	Dropdown background
`--sd-ui-comments-dropdown-border`	inherits `--sd-ui-border`	Dropdown border
`--sd-ui-comments-dropdown-shadow`	`0 8px 24px rgba(0,0,0,0.12)`	Dropdown shadow
`--sd-ui-comments-option-text`	inherits body text	Option text
`--sd-ui-comments-option-hover-text`	inherits option text	Hovered option
`--sd-ui-comments-option-hover-bg`	inherits `--sd-ui-hover-bg`	Option hover
`--sd-ui-comments-option-size`	`14px`	Option size

Visibility badges:

Variable	Default	Controls
`--sd-ui-comments-internal-bg`	`#cde6e6`	Internal badge
`--sd-ui-comments-external-bg`	`#f5cfda`	External badge

Comment highlights (in-document)

Colors applied to highlighted text when comments are present. These are document-level, not UI chrome.

Variable	Default	Controls
`--sd-comments-highlight-external`	`#b1124b40`	External highlight
`--sd-comments-highlight-external-active`	`#b1124b66`	Active external
`--sd-comments-highlight-external-faded`	`#b1124b20`	Faded external
`--sd-comments-highlight-external-nested-border`	`#b1124b99`	Nested left border
`--sd-comments-highlight-internal`	`#07838340`	Internal highlight
`--sd-comments-highlight-internal-active`	`#07838366`	Active internal
`--sd-comments-highlight-internal-faded`	`#07838320`	Faded internal
`--sd-comments-highlight-internal-nested-border`	`#07838399`	Nested left border
`--sd-comments-highlight-hover`	`#1354ff55`	Hover highlight
`--sd-comments-selection-background`	`#1354ff55`	Selection highlight

Tracked changes

Insert, delete, and format change decorations in the document.

Variable	Default	Controls
`--sd-tracked-changes-insert-background`	`#399c7222`	Insert highlight
`--sd-tracked-changes-insert-border`	`#00853d`	Insert border color
`--sd-tracked-changes-insert-border-width`	`1px`	Insert border width
`--sd-tracked-changes-insert-text`	`currentColor`	Insert text color
`--sd-tracked-changes-insert-decoration-line`	`none`	Insert text decoration
`--sd-tracked-changes-insert-decoration-thickness`	`1px`	Insert decoration thickness
`--sd-tracked-changes-insert-underline-offset`	`0px`	Insert underline offset
`--sd-tracked-changes-delete-background`	`#cb0e4722`	Delete highlight
`--sd-tracked-changes-delete-border`	`#cb0e47`	Delete border color
`--sd-tracked-changes-delete-border-width`	`1px`	Delete border width
`--sd-tracked-changes-delete-text`	`currentColor`	Delete text color
`--sd-tracked-changes-delete-decoration-thickness`	`2px`	Delete strike thickness
`--sd-tracked-changes-format-border`	`gold`	Format change border
`--sd-tracked-changes-insert-background-focused`	`#399c7244`	Focused insert
`--sd-tracked-changes-delete-background-focused`	`#cb0e4744`	Focused delete
`--sd-tracked-changes-format-background-focused`	`#ffd70033`	Focused format change

Word-style redlines can be approximated with CSS vars only:

.word-like-redlines {
  --sd-tracked-changes-insert-border-width: 0px;
  --sd-tracked-changes-insert-background: transparent;
  --sd-tracked-changes-insert-text: #bf3848;
  --sd-tracked-changes-insert-decoration-line: underline;
  --sd-tracked-changes-insert-decoration-thickness: 1.5px;
  --sd-tracked-changes-insert-underline-offset: 2px;

  --sd-tracked-changes-delete-border-width: 0px;
  --sd-tracked-changes-delete-background: transparent;
  --sd-tracked-changes-delete-text: #2e64a8;
  --sd-tracked-changes-delete-decoration-thickness: 1.5px;
}

If you also want tracked-change text inside comment threads to match, set --sd-ui-comments-insert-text and --sd-ui-comments-delete-text too.

Content controls

DOCX content controls (SDTs): form fields, dropdowns, date pickers.

Variable	Default	Controls
`--sd-content-controls-block-border`	`#629be7`	Block control border
`--sd-content-controls-block-hover-bg`	inherits `--sd-ui-hover-bg`	Block hover
`--sd-content-controls-inline-border`	`#629be7`	Inline control border
`--sd-content-controls-inline-hover-bg`	inherits `--sd-ui-hover-bg`	Inline hover
`--sd-content-controls-label-border`	`#629be7`	Label border
`--sd-content-controls-label-bg`	`#629be7ee`	Label background
`--sd-content-controls-label-text`	`#ffffff`	Label text
`--sd-content-controls-lock-hover-bg`	`rgba(98,155,231,0.08)`	Locked control hover

Layout

Page appearance in presentation mode.

Variable	Default	Controls
`--sd-layout-page-bg`	inherits `--sd-ui-bg`	Page background
`--sd-layout-page-shadow`	`0 4px 20px rgba(15,23,42,0.08)`	Page shadow

Tools

The floating action toolbar for AI and insert actions.

Variable	Default	Controls
`--sd-ui-tools-gap`	`6px`	Gap between items
`--sd-ui-tools-item-size`	`50px`	Button size
`--sd-ui-tools-item-radius`	`12px`	Button radius
`--sd-ui-tools-item-bg`	`rgba(219,219,219,0.6)`	Button background
`--sd-ui-tools-icon-size`	`20px`	Icon size

Surfaces

Dialog and floating overlays rendered above document content. Style with CSS variables: the stable classes .sd-surface-dialog and .sd-surface-floating are also available for stylesheet targeting.

Variable	Default	Controls
`--sd-ui-surface-bg`	inherits `--sd-ui-bg`	Surface background
`--sd-ui-surface-border`	inherits `--sd-ui-border`	Surface border color
`--sd-ui-surface-shadow`	`0 8px 32px rgba(0,0,0,0.18)`	Surface box shadow
`--sd-ui-surface-radius`	inherits `--sd-radius-200`	Surface border radius
`--sd-ui-surface-z-index`	`100`	Base z-index for surface layers
`--sd-ui-surface-title-padding`	`16px 20px 0`	Title area padding
`--sd-ui-surface-content-padding`	`16px 20px 20px`	Content area padding
`--sd-ui-dialog-backdrop`	`rgba(0,0,0,0.4)`	Dialog backdrop color
`--sd-ui-dialog-max-width`	`480px`	Dialog max-width
`--sd-ui-floating-width`	`360px`	Floating surface default width
`--sd-ui-floating-max-width`	`480px`	Floating surface max width
`--sd-ui-floating-max-height`	`min(60vh, calc(100% - 32px))`	Floating surface max height
`--sd-ui-floating-edge-offset`	`16px`	Offset from edges for placement presets

Find and replace

The built-in find/replace popover inherits the shared surface tokens above and adds its own control-level variables.

Variable	Default	Controls
`--sd-ui-find-replace-gap`	`8px`	Vertical gap between main rows
`--sd-ui-find-replace-input-height`	`30px`	Input height
`--sd-ui-find-replace-input-padding`	`4px 8px`	Input padding
`--sd-ui-find-replace-input-font-size`	inherits `--sd-ui-font-size-400`	Input font size
`--sd-ui-find-replace-input-bg`	inherits `--sd-ui-surface-bg`	Input background
`--sd-ui-find-replace-input-border`	inherits `--sd-ui-border`	Input border color
`--sd-ui-find-replace-input-focus-border`	inherits `--sd-ui-action`	Input border on focus
`--sd-ui-find-replace-input-radius`	`4px`	Input border radius
`--sd-ui-find-replace-count-color`	inherits `--sd-ui-text-muted`	Match-count text color
`--sd-ui-find-replace-count-font-size`	inherits `--sd-ui-font-size-300`	Match-count font size
`--sd-ui-find-replace-count-inset`	`8px`	Right inset for the match-count overlay inside the input
`--sd-ui-find-replace-btn-size`	`28px`	Icon-button size
`--sd-ui-find-replace-btn-radius`	`4px`	Icon-button border radius
`--sd-ui-find-replace-btn-hover-bg`	inherits `--sd-ui-hover-bg`	Icon-button hover background
`--sd-ui-find-replace-btn-color`	inherits `--sd-ui-text`	Icon-button color
`--sd-ui-find-replace-btn-disabled-opacity`	`0.4`	Icon-button opacity when disabled
`--sd-ui-find-replace-btn-icon-font-size`	`12px`	Prev/next/close icon size
`--sd-ui-find-replace-btn-toggle-font-size`	`12px`	Text-toggle font size
`--sd-ui-find-replace-btn-toggle-padding`	`4px 8px`	Text-toggle padding
`--sd-ui-find-replace-toggle-active-bg`	inherits `--sd-color-blue-100`	Active background for option toggles
`--sd-ui-find-replace-toggle-active-color`	inherits `--sd-color-blue-700`	Active text/icon color for option toggles
`--sd-ui-find-replace-action-btn-bg`	inherits `--sd-ui-action`	Replace button background
`--sd-ui-find-replace-action-btn-color`	`#fff`	Replace button text color
`--sd-ui-find-replace-action-btn-hover-bg`	inherits `--sd-ui-action-hover`	Replace button hover background
`--sd-ui-find-replace-action-btn-padding`	`4px 10px`	Replace button padding
`--sd-ui-find-replace-nav-gap`	`2px`	Gap between prev/next/close buttons
`--sd-ui-find-replace-options-gap`	`4px`	Gap between the lower-row toggles/actions

Search highlights

Colors used for search result highlights inside the document view.

Variable	Default	Controls
`--sd-ui-search-match-bg`	`rgba(255, 213, 0, 0.4)`	Background for non-active search matches
`--sd-ui-search-match-active-bg`	`rgba(255, 150, 0, 0.6)`	Background for the active search match

Password prompt

The built-in password dialog for encrypted DOCX files. All variables default to the shared UI tokens.

Variable	Default	Controls
`--sd-ui-password-prompt-gap`	`12px`	Vertical spacing between sections
`--sd-ui-password-prompt-heading-size`	inherits `--sd-ui-font-size-500`	Heading font size
`--sd-ui-password-prompt-heading-weight`	`600`	Heading font weight
`--sd-ui-password-prompt-heading-color`	inherits `--sd-ui-text`	Heading text color
`--sd-ui-password-prompt-description-size`	inherits `--sd-ui-font-size-400`	Description font size
`--sd-ui-password-prompt-description-color`	inherits `--sd-ui-text`	Description text color
`--sd-ui-password-prompt-input-padding`	`8px 10px`	Input padding
`--sd-ui-password-prompt-input-size`	inherits `--sd-ui-font-size-400`	Input font size
`--sd-ui-password-prompt-input-color`	inherits `--sd-ui-text`	Input text color
`--sd-ui-password-prompt-input-bg`	inherits `--sd-ui-surface-bg`	Input background
`--sd-ui-password-prompt-input-border`	inherits `--sd-ui-border`	Input border color
`--sd-ui-password-prompt-input-focus-border`	inherits `--sd-ui-action`	Input border on focus
`--sd-ui-password-prompt-input-radius`	`4px`	Input border radius
`--sd-ui-password-prompt-input-disabled-opacity`	`0.6`	Input opacity when disabled/busy
`--sd-ui-password-prompt-error-size`	inherits `--sd-ui-font-size-300`	Error message font size
`--sd-ui-password-prompt-error-color`	inherits `--sd-color-red-500`	Error message color
`--sd-ui-password-prompt-actions-gap`	`8px`	Gap between buttons
`--sd-ui-password-prompt-btn-padding`	`6px 16px`	Button padding
`--sd-ui-password-prompt-btn-size`	inherits `--sd-ui-font-size-400`	Button font size
`--sd-ui-password-prompt-btn-radius`	`4px`	Button border radius
`--sd-ui-password-prompt-btn-disabled-opacity`	`0.5`	Button opacity when disabled
`--sd-ui-password-prompt-cancel-bg`	`transparent`	Cancel button background
`--sd-ui-password-prompt-cancel-border`	inherits `--sd-ui-border`	Cancel button border
`--sd-ui-password-prompt-cancel-color`	inherits `--sd-ui-text`	Cancel button text color
`--sd-ui-password-prompt-cancel-hover-bg`	inherits `--sd-color-gray-100`	Cancel button hover background
`--sd-ui-password-prompt-submit-bg`	inherits `--sd-ui-action`	Submit button background
`--sd-ui-password-prompt-submit-border`	inherits `--sd-ui-action`	Submit button border
`--sd-ui-password-prompt-submit-color`	inherits `--sd-ui-action-text`	Submit button text color
`--sd-ui-password-prompt-submit-hover-bg`	inherits `--sd-ui-action-hover`	Submit button hover background

Source files

Token definitions live in your node_modules/superdoc/ package:

src/assets/styles/helpers/variables.css: defaults
src/assets/styles/helpers/themes.css: preset themes
src/assets/styles/helpers/compat.css: aliases for old names that map to a different concept

Getting Started

Editor

Document Engine

AI

Solutions

Resources

`createTheme()` options

Dark theme example

Raw CSS alternative

Variable reference

Semantic (UI-wide)

Dropdowns

Context menu

Tooltip

Comments

Comment highlights (in-document)

Tracked changes

Content controls

Layout

Tools

Surfaces

Find and replace

Search highlights

Password prompt

Source files

​createTheme() options

​Dark theme example

​Raw CSS alternative

​Variable reference

​Semantic (UI-wide)

​Toolbar

​Dropdowns

​Context menu

​Tooltip

​Comments

​Comment highlights (in-document)

​Tracked changes

​Content controls

​Layout

​Tools

​Surfaces

​Find and replace

​Search highlights

​Password prompt

​Source files

`createTheme()` options

Dark theme example

Raw CSS alternative

Variable reference

Semantic (UI-wide)

Toolbar

Dropdowns

Context menu

Tooltip

Comments

Comment highlights (in-document)

Tracked changes

Content controls

Layout

Tools

Surfaces

Find and replace

Search highlights

Password prompt

Source files