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

# Theming API

> Types and utilities for the email theming system.

## EmailTheming extension

The `EmailTheming` extension from `@vuemaildev/editor/plugins` adds theme-aware styling
to the editor and provides a `SerializerPlugin` for theme-aware HTML export.

```ts theme={null}
import { EmailTheming } from '@vuemaildev/editor/plugins';

const extensions = [StarterKit, EmailTheming.configure({ theme: 'basic' })];
```

**theme** `EditorThemeInput` (default: 'basic')

The active theme. Accepts a built-in preset (`'basic'` or `'minimal'`) or a `ThemeConfig`
object for custom themes.

## Types

### EditorTheme

```ts theme={null}
type EditorTheme = 'basic' | 'minimal';
```

***

### EditorThemeInput

The widened theme type accepted by the `theme` prop and `EmailTheming.configure()`:

```ts theme={null}
type EditorThemeInput = EditorTheme | ThemeConfig;
```

***

### ThemeableComponent

The subset of `KnownThemeComponents` that can be customized via `ThemeComponentStyles`:

```ts theme={null}
type ThemeableComponent =
  | 'body'
  | 'container'
  | 'h1'
  | 'h2'
  | 'h3'
  | 'link'
  | 'image'
  | 'button'
  | 'codeBlock'
  | 'inlineCode'
  | 'listItem'
  | 'list'
  | 'nestedList'
  | 'paragraph';
```

***

### ThemeComponentStyles

CSS-in-JS styles keyed by themeable component name, using Vue's `CSSProperties`:

```ts theme={null}
type ThemeComponentStyles = {
  [K in ThemeableComponent]?: CSSProperties & {
    align?: 'center' | 'left' | 'right';
  };
};
```

***

### ThemeConfig

A custom theme configuration object:

```ts theme={null}
interface ThemeConfig {
  extends?: EditorTheme;
  styles: ThemeComponentStyles;
}
```

**extends** `EditorTheme`

The built-in theme to inherit from. If omitted, uses `'minimal'` reset styles as a base.

**styles** `ThemeComponentStyles` *required*

CSS-in-JS styles keyed by component name. Values are merged on top of the base theme.

***

### KnownThemeComponents

All component keys that a theme can style:

```ts theme={null}
type KnownThemeComponents =
  | 'reset'
  | 'body'
  | 'container'
  | 'h1'
  | 'h2'
  | 'h3'
  | 'paragraph'
  | 'nestedList'
  | 'list'
  | 'bulletList'
  | 'orderedList'
  | 'listItem'
  | 'listParagraph'
  | 'blockquote'
  | 'codeBlock'
  | 'inlineCode'
  | 'codeTag'
  | 'link'
  | 'footer'
  | 'hr'
  | 'image'
  | 'button'
  | 'section';
```

***

### KnownCssProperties

CSS properties that can be customized per theme component:

**Layout:** `align`, `width`, `height`, `margin`, `padding`, `paddingTop`, `paddingRight`,
`paddingBottom`, `paddingLeft`

**Appearance:** `backgroundColor`, `borderRadius`, `borderTopLeftRadius`, `borderTopRightRadius`,
`borderBottomLeftRadius`, `borderBottomRightRadius`, `borderWidth`, `borderStyle` and `borderColor`,
and the `Top`, `Right`, `Bottom` and `Left` variants of the last three, like `borderTopWidth`

**Typography:** `color`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `textDecoration`

***

### CssJs

A mapping of theme component keys to CSS properties:

```ts theme={null}
type CssJs = {
  [K in KnownThemeComponents]: CSSProperties & {
    align?: 'center' | 'left' | 'right';
  };
};
```

***

### PanelGroup

Represents a group of configurable theme properties for a component:

```ts theme={null}
interface PanelGroup {
  id?: PanelSectionId;
  title: string;
  category?: string;
  headerSlot?: VNodeChild;
  classReference?: KnownThemeComponents;
  inputs: Omit<PanelInputProperty, 'category'>[];
}
```

***

### PanelInputProperty

An individual configurable CSS property within a panel:

```ts theme={null}
interface PanelInputProperty {
  label: string;
  type: 'color' | 'number' | 'select' | 'text' | 'textarea';
  value?: string | number;
  prop: KnownCssProperties;
  classReference?: KnownThemeComponents;
  unit?: 'px' | '%';
  options?: Record<string, string>;
  placeholder?: string;
  category: 'layout' | 'appearance' | 'typography';
}
```

## Theme helpers

### createTheme

Creates a custom theme from scratch (uses `minimal` reset as base):

```ts theme={null}
import { createTheme } from '@vuemaildev/editor/plugins';

const theme = createTheme({
  body: { backgroundColor: '#1a1a2e', color: '#e2e8f0' },
  button: { backgroundColor: '#3b82f6', color: '#fff' },
});
```

**styles** `ThemeComponentStyles` *required*

CSS-in-JS styles keyed by component name.

Returns a `ThemeConfig` object.

***

### extendTheme

Extends a built-in theme with style overrides:

```ts theme={null}
import { extendTheme } from '@vuemaildev/editor/plugins';

const theme = extendTheme('basic', {
  body: { backgroundColor: '#eff6ff' },
  button: { backgroundColor: '#2563eb', borderRadius: '6px' },
});
```

**base** `EditorTheme` *required*

The built-in theme to extend (`'basic'` or `'minimal'`).

**overrides** `ThemeComponentStyles` *required*

CSS-in-JS styles to merge on top of the base theme.

Returns a `ThemeConfig` object.

***

## Utility functions

### getMergedCssJs

Merges the base theme styles with custom panel overrides:

```ts theme={null}
import { getMergedCssJs } from '@vuemaildev/editor/plugins';

const mergedStyles = getMergedCssJs(theme, panelStyles);
```

**theme** `EditorTheme` *required*

The active theme to use as a base.

**panelStyles** `PanelGroup[]`

Custom style overrides from the theme panel UI.

***

### getResolvedNodeStyles

Resolves the final CSS styles for a specific node based on theme and document depth:

```ts theme={null}
import { getResolvedNodeStyles } from '@vuemaildev/editor/plugins';

const styles = getResolvedNodeStyles(node, depth, mergedCssJs);
```

**node** `JSONContent` *required*

The TipTap node to resolve styles for.

**depth** `number` *required*

The node's depth in the document tree. Affects styles for nested elements (e.g., nested lists).

**mergedCssJs** `CssJs` *required*

The merged theme styles from `getMergedCssJs`.

***

### getThemeComponentKey

Maps a node type and depth to a theme component key:

```ts theme={null}
import { getThemeComponentKey } from '@vuemaildev/editor/plugins';

const paragraphKey = getThemeComponentKey('paragraph', 0); // 'paragraph'
const nestedListKey = getThemeComponentKey('bulletList', 2); // 'nestedList'
```

***

### stylesToCss

Converts a theme's style definitions to a CSS object:

```ts theme={null}
import { stylesToCss } from '@vuemaildev/editor/plugins';

const css = stylesToCss(styles, theme);
```

***

### useEmailTheming

Composable that provides access to the current theme state from within the editor. It takes the
editor, or a ref or getter of it, and returns a ref that updates as the document changes:

```vue theme={null}
<script setup lang="ts">
import { useCurrentEditor } from '@vuemaildev/editor/core';
import { useEmailTheming } from '@vuemaildev/editor/plugins';

const { editor } = useCurrentEditor();
const theming = useEmailTheming(editor);
// Access theming.value?.styles, theming.value?.theme, theming.value?.css
</script>
```

`theming.value` is `null` until the editor is created.


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