Skip to main content
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.
VariableDefaultControls
--sd-ui-font-familyArial, Helvetica, sans-serifUI font
--sd-ui-text#47484aPrimary text
--sd-ui-text-muted#666666Secondary text
--sd-ui-text-disabled#abababDisabled text
--sd-ui-bg#ffffffDefault background
--sd-ui-hover-bg#dbdbdbHover background
--sd-ui-active-bg#c8d0d8Active/pressed background
--sd-ui-disabled-bg#f5f5f5Disabled background
--sd-ui-border#dbdbdbDefault border
--sd-ui-action#1355ffAction/accent color
--sd-ui-action-hover#0f44ccAction hover
--sd-ui-action-text#ffffffText on action buttons
--sd-ui-shadow0 4px 12px rgba(0,0,0,0.12)Default shadow
--sd-ui-radius6pxDefault border radius

Toolbar

VariableDefaultControls
--sd-ui-toolbar-height32pxRow height
--sd-ui-toolbar-padding-x16pxHorizontal padding
--sd-ui-toolbar-padding-y4pxVertical padding
--sd-ui-toolbar-item-gap2pxGap between buttons
--sd-ui-toolbar-item-padding5pxButton padding
--sd-ui-toolbar-bgtransparentBackground
--sd-ui-toolbar-button-textinherits --sd-ui-textButton text/icon color
--sd-ui-toolbar-button-hover-bginherits --sd-ui-hover-bgButton hover
--sd-ui-toolbar-button-active-bginherits --sd-ui-active-bgButton active
Toolbar dropdowns (font picker, style picker) and the overflow menu.
VariableDefaultControls
--sd-ui-dropdown-bginherits --sd-ui-bgPanel background
--sd-ui-dropdown-borderinherits --sd-ui-borderPanel border
--sd-ui-dropdown-textinherits --sd-ui-textOption text
--sd-ui-dropdown-hover-textinherits dropdown textHovered option text
--sd-ui-dropdown-selected-textinherits dropdown textSelected option text
--sd-ui-dropdown-hover-bginherits --sd-ui-hover-bgOption hover
--sd-ui-dropdown-active-bginherits --sd-ui-active-bgOption active
--sd-ui-dropdown-option-radius3pxOption border radius
--sd-ui-dropdown-shadow0 8px 24px rgba(0,0,0,0.16)Panel shadow

Context menu

The right-click menu.
VariableDefaultControls
--sd-ui-menu-bginherits --sd-ui-bgBackground
--sd-ui-menu-textinherits --sd-ui-textText
--sd-ui-menu-font-size12pxText size
--sd-ui-menu-radius0Border radius
--sd-ui-menu-borderinherits --sd-ui-borderBorder
--sd-ui-menu-shadow0 0 0 1px rgba(0,0,0,0.05), 0 10px 20px rgba(0,0,0,0.1)Shadow
--sd-ui-menu-input-borderinherits --sd-ui-borderSearch input border
--sd-ui-menu-input-focus-borderinherits --sd-ui-actionSearch input focus
--sd-ui-menu-item-hover-bginherits --sd-ui-hover-bgItem hover
--sd-ui-menu-item-active-bginherits --sd-ui-active-bgActive item
--sd-ui-menu-item-active-textinherits --sd-ui-actionActive item text

Tooltip

VariableDefaultControls
--sd-ui-tooltip-bg#262626Background (intentionally dark)
--sd-ui-tooltip-text#ffffffText (intentionally light)
--sd-ui-tooltip-radius6pxBorder radius
--sd-ui-tooltip-shadow0 3px 12px rgba(0,0,0,0.28)Shadow

Comments

Card styling, typography, and input elements for the comments sidebar. Card:
VariableDefaultControls
--sd-ui-comments-card-bg#f3f6fdDefault card
--sd-ui-comments-card-hover-bginherits card bgHovered card
--sd-ui-comments-card-active-bginherits --sd-ui-bgSelected card
--sd-ui-comments-card-resolved-bginherits --sd-ui-disabled-bgResolved card
--sd-ui-comments-card-active-borderinherits --sd-ui-borderSelected card border
--sd-ui-comments-card-radius12pxCard radius
--sd-ui-comments-card-padding16pxCard padding
--sd-ui-comments-card-shadow0 4px 12px rgba(50,50,50,0.15)Card shadow
--sd-ui-comments-transitionall 200ms easeAnimation
--sd-ui-comments-separatorinherits --sd-ui-borderDivider line
Text:
VariableDefaultControls
--sd-ui-comments-author-textinherits --sd-ui-textAuthor name
--sd-ui-comments-author-size14pxAuthor size
--sd-ui-comments-author-weight600Author weight
--sd-ui-comments-timestamp-textinherits --sd-ui-text-mutedTimestamp
--sd-ui-comments-timestamp-size12pxTimestamp size
--sd-ui-comments-body-textinherits --sd-ui-textBody text
--sd-ui-comments-body-size14pxBody size
Input:
VariableDefaultControls
--sd-ui-comments-input-bginherits --sd-ui-bgInput background
--sd-ui-comments-input-borderinherits --sd-ui-borderInput border
Status:
VariableDefaultControls
--sd-ui-comments-resolved-text#00853d”Resolved” badge
--sd-ui-comments-insert-text#00853dTracked change insert
--sd-ui-comments-delete-text#cb0e47Tracked change delete
Filter dropdown:
VariableDefaultControls
--sd-ui-comments-dropdown-bginherits --sd-ui-bgDropdown background
--sd-ui-comments-dropdown-borderinherits --sd-ui-borderDropdown border
--sd-ui-comments-dropdown-shadow0 8px 24px rgba(0,0,0,0.12)Dropdown shadow
--sd-ui-comments-option-textinherits body textOption text
--sd-ui-comments-option-hover-textinherits option textHovered option
--sd-ui-comments-option-hover-bginherits --sd-ui-hover-bgOption hover
--sd-ui-comments-option-size14pxOption size
Visibility badges:
VariableDefaultControls
--sd-ui-comments-internal-bg#cde6e6Internal badge
--sd-ui-comments-external-bg#f5cfdaExternal badge

Comment highlights (in-document)

Colors applied to highlighted text when comments are present. These are document-level, not UI chrome.
VariableDefaultControls
--sd-comments-highlight-external#b1124b40External highlight
--sd-comments-highlight-external-active#b1124b66Active external
--sd-comments-highlight-external-faded#b1124b20Faded external
--sd-comments-highlight-external-nested-border#b1124b99Nested left border
--sd-comments-highlight-internal#07838340Internal highlight
--sd-comments-highlight-internal-active#07838366Active internal
--sd-comments-highlight-internal-faded#07838320Faded internal
--sd-comments-highlight-internal-nested-border#07838399Nested left border
--sd-comments-highlight-hover#1354ff55Hover highlight
--sd-comments-selection-background#1354ff55Selection highlight

Tracked changes

Insert, delete, and format change decorations in the document.
VariableDefaultControls
--sd-tracked-changes-insert-background#399c7222Insert highlight
--sd-tracked-changes-insert-border#00853dInsert left border
--sd-tracked-changes-delete-background#cb0e4722Delete highlight
--sd-tracked-changes-delete-border#cb0e47Delete left border
--sd-tracked-changes-format-bordergoldFormat change border
--sd-tracked-changes-insert-background-focused#399c7244Focused insert
--sd-tracked-changes-delete-background-focused#cb0e4744Focused delete
--sd-tracked-changes-format-background-focused#ffd70033Focused format change

Content controls

DOCX content controls (SDTs) — form fields, dropdowns, date pickers.
VariableDefaultControls
--sd-content-controls-block-border#629be7Block control border
--sd-content-controls-block-hover-bginherits --sd-ui-hover-bgBlock hover
--sd-content-controls-inline-border#629be7Inline control border
--sd-content-controls-inline-hover-bginherits --sd-ui-hover-bgInline hover
--sd-content-controls-label-border#629be7Label border
--sd-content-controls-label-bg#629be7eeLabel background
--sd-content-controls-label-text#ffffffLabel text
--sd-content-controls-lock-hover-bgrgba(98,155,231,0.08)Locked control hover

Layout

Page appearance in presentation mode.
VariableDefaultControls
--sd-layout-page-bginherits --sd-ui-bgPage background
--sd-layout-page-shadow0 4px 20px rgba(15,23,42,0.08)Page shadow

Tools

The floating action toolbar for AI and insert actions.
VariableDefaultControls
--sd-ui-tools-gap6pxGap between items
--sd-ui-tools-item-size50pxButton size
--sd-ui-tools-item-radius12pxButton radius
--sd-ui-tools-item-bgrgba(219,219,219,0.6)Button background
--sd-ui-tools-icon-size20pxIcon size

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