> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom themes

Full `createTheme()` API reference and CSS variable catalog. Start with the [theming overview](https://docs.superdoc.dev/getting-started/theming.md) if you're new to theming.

## `createTheme()` options

```javascript theme={null}
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);
```

> [!TIP]
>
> Start with `colors` only. Use `vars` when a specific component needs to look different.

## Dark theme example

```javascript theme={null}
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>`.

```css theme={null}
.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 |

### Toolbar

| 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 |

### Context menu

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 |

### Tooltip

| 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:

```css theme={null}
.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.

These theme the **built-in** chrome (`modules.contentControls.chrome: 'default'`). If you turn the chrome off (`chrome: 'none'`) to draw your own field/clause look, style the controls with the `--sd-content-controls-custom-*` variables instead. See [Custom UI > Content controls](https://docs.superdoc.dev/editor/custom-ui/content-controls.md).

| 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.