Theme Colors Manipulation

Arbitrary Color Values

TextMate themes normally expect the color values of each token to be a valid hex color value.
This limitation is inherited from vscode-textmate.
In Shiki v0.9.15 we introduced an automatic workaround: non‑hex color values are temporarily replaced with a placeholder and restored during tokenization.
This lets you use themes with arbitrary color values for rendering without worrying about the technical details.

import { createHighlighter } from 'shiki';

const highlighter = await createHighlighter({
  langs: ['javascript'],
  themes: [
    {
      name: 'my-theme',
      settings: [
        {
          scope: ['comment'],
          settings: {
            // use `rgb`, `hsl`, `hsla`,
            // or any anything supported by your renderer
            foreground: 'rgb(128, 128, 128)'
          }
        },
        {
          scope: ['string'],
          settings: {
            foreground: 'var(--code-string)' // CSS variable
          }
        },
        // ...more
      ],
      // Background and foreground colors
      bg: 'var(--code-bg)',
      fg: 'var(--code-fg)'
    }
  ]
});

const html = highlighter.codeToHtml('const foo = "bar"', {
  lang: 'javascript',
  theme: 'my-theme'
});

Notice
Use this carefully as this will diverge from TextMate theme compatibility.
This may make the theme incompatible with non‑web usage such as shiki-cli and shiki-monaco.

Learn more about how to load themes.

Color Replacements

You can also use the colorReplacements option to replace the color values of the theme.
This is useful when you want to use a theme with a different color palette.
It can be provided on both the theme object and the codeToHast / codeToHtml options.

The colorReplacements object follows a color‑to‑color format, where the keys represent the color to be replaced and the value represents the new color:

const html = await codeToHtml(
  code,
  {
    lang: 'js',
    theme: 'min-dark',
    colorReplacements: {
      '#ff79c6': '#189eff'
    }
  }
);

In addition, colorReplacements may contain scoped replacements.
This is useful when you provide multiple themes and want to replace the colors of a specific theme:

const html = await codeToHtml(
  code,
  {
    lang: 'js',
    themes: {
      dark: 'min-dark',
      light: 'min-light'
    },
    colorReplacements: {
      'min-dark': {
        '#ff79c6': '#189eff'
      },
      'min-light': {
        '#ff79c6': '#defdef'
      }
    }
  }
);

This is only allowed for the colorReplacements option and not for the theme object.

CSS Variables Theme

Shiki provides a factory function helper createCssVariablesTheme for creating a theme that uses CSS variables more easily.
Note that this theme is a lot less granular than most of the other themes and requires you to define the CSS variables in your app.
It is provided for easier migration from Shiki’s css‑variables theme.
For better highlighting results, we recommend constructing the theme manually with Arbitrary Color Values or using Color Replacements to override an existing theme.

This theme is not included by default and must be registered explicitly:

import { createHighlighter } from 'shiki';
import { createCssVariablesTheme } from 'shiki/core';

// Create a custom CSS variables theme, the following are the default values
const myTheme = createCssVariablesTheme({
  name: 'css-variables',
  variablePrefix: '--shiki-',
  variableDefaults: {},
  fontStyle: true
});

const highlighter = await createHighlighter({
  langs: ['javascript'],
  themes: [myTheme]
});

const html = await highlighter.codeToHtml(
  'const foo = "bar"',
  { lang: 'javascript', theme: myTheme }
);