Theme API

@tanstack/highlight/theme converts portable theme objects into CSS custom properties and base styles. It contains no bundled theme.

themeTokenClasses

A readonly list containing token and every semantic HighlightTokenClass. Use it to validate or generate a complete theme.

HighlightThemeToken

The union derived from themeTokenClasses.

HighlightTheme

type HighlightTheme = {
  background: string
  foreground: string
  name: string
  tokens: Record<HighlightThemeToken, string>
  type: 'dark' | 'light'
}

Every token color is required. foreground describes the theme and tokens.token is the emitted default token color.

CreateThemeCssOptions

Use either a light/dark pair or an explicit selector list:

type CreateThemeCssOptions = {
  codeBlockSelector?: string
  includeBaseStyles?: boolean
  lineNumbersSelector?: string
  lightSelector?: string
  darkSelector?: string
} & (
  | { light: HighlightTheme; dark?: HighlightTheme }
  | { dark: HighlightTheme; light?: HighlightTheme }
  | {
      themes: ReadonlyArray<{
        selector: string
        theme: HighlightTheme
      }>
    }
)

Pair mode defaults to :root for light and .dark for dark. includeBaseStyles defaults to true. Base styles target pre.th-code and .th-code--line-numbers unless codeBlockSelector and lineNumbersSelector override them.

ThemeBaseCssOptions

type ThemeBaseCssOptions = {
  codeBlockSelector?: string
  lineNumbersSelector?: string
}

Use custom selectors when a Markdown or framework renderer owns the outer code-block classes.

createThemeCss

function createThemeCss(options: CreateThemeCssOptions): string

Returns theme-variable rules followed by base code-block CSS unless includeBaseStyles is false.

createThemeRule

function createThemeRule(selector: string, theme: HighlightTheme): string

Returns one selector block defining --th-background, --th-token, and every semantic --th-* color.

createThemeBaseCss

function createThemeBaseCss(options?: ThemeBaseCssOptions): string

Returns the structural styles and variable lookups for code blocks, tokens, line wrappers, and line numbers. It does not set fonts, borders, radii, or application layout.

See Themes for isolated imports and custom themes.