Decorations

We provide a decorations API allowing you to wrap custom classes and attributes around ranges of your code.

import { codeToHtml } from 'shiki'

const code = `
const x = 10
console.log(x)
`.trim()

const html = await codeToHtml(code, {
  theme: 'vitesse-light',
  lang: 'ts',
  decorations: [ 
    {
      // line and character are 0-indexed
      start: { line: 1, character: 0 },
      end: { line: 1, character: 11 },
      properties: { class: 'highlighted-word' }
    }
  ]
})

The result will be (styled with CSS in this example):

const x = 10
console.log(x)

The positions can also be 0-indexed offsets relative to the code:

const html = await codeToHtml(code, {
  theme: 'vitesse-light',
  lang: 'ts',
  decorations: [ 
    {
      start: 21,
      end: 24,
      properties: { class: 'highlighted-word' }
    }
  ]
})

It renders:

const x = 10
console.log(x)

Negative character positions denote characters from the end of a line, starting with the line end:

const item: DecorationItem = {
  start: { line: 0, character: 0 },
  end: { line: 0, character: -1 },
  properties: { class: 'highlighted-word' }
}

This highlights the entire first line:

const x = 10
console.log(x)

Use Decorations in Transformers

For advanced use cases, you can use the Transformers API to have full access to the tokens and the HAST tree.

Meanwhile, if you want to append decorations within a transformer, you can do that with:

import { codeToHtml, ShikiTransformer } from 'shiki'

const myTransformer: ShikiTransformer = {
  name: 'my-transformer',
  preprocess(code, options) {
    // Generate the decorations somehow
    const decorations = doSomethingWithCode(code)

    // Make sure the decorations array exists
    options.decorations ||= []
    // Append the decorations
    options.decorations.push(...decorations)
  }
}

const html = await codeToHtml(code, {
  theme: 'vitesse-light',
  lang: 'ts',
  transformers: [
    myTransformer
  ]
})

Note that you can only provide decorations in or before the preprocess hook. In later hooks, changes to the decorations array will be ignored.