Core API

@tanstack/highlight/core contains the engine and renderers. It does not import a language or theme.

Language registration

LanguageDefinition

type LanguageDefinition<Name extends string = string> = {
  aliases?: ReadonlyArray<string>
  name: Name
  tokenize: (
    code: string,
    context: TokenizerContext,
  ) => ReadonlyArray<TokenRange>
}

A language registration. The tokenizer returns semantic ranges in the original source.

TokenRange

type TokenRange = {
  className: HighlightTokenClass
  start: number
  end: number
}

start is inclusive and end is exclusive. Both are zero-based UTF-16 string offsets. The highlighter clamps integer offsets to the source bounds, sorts ranges, and skips overlaps. Non-integer offsets are ignored.

TokenizerContext

type TokenizerContext = {
  hasLanguage: (lang: string) => boolean
  tokenize: (code: string, lang: string) => Array<TokenRange>
}

Passed to language tokenizers for opt-in embedded-language delegation. Recursive calls are capped at 24 levels.

defineLanguage

function defineLanguage<const Name extends string>(
  definition: LanguageDefinition<Name>,
): LanguageDefinition<Name>

An identity helper that preserves the literal language name and validates the definition with TypeScript.

createHighlighter

function createHighlighter(options: {
  fallbackLanguage?: string
  languages: ReadonlyArray<LanguageDefinition>
}): Highlighter

Builds an immutable highlighter interface from the supplied registrations. The default fallback name is plaintext. An unregistered language, including an unregistered fallback, is rendered as escaped plain text.

Duplicate canonical names or aliases use the last registration encountered.

Highlighter

Highlighter

type Highlighter = {
  highlight(code: string, options?: HighlightOptions): HighlightResult
  highlightToHtml(code: string, options?: HighlightOptions): string
  listLanguages(): Array<string>
  normalizeLanguage(lang?: string): string
  renderCodeBlockData(options: RenderCodeBlockOptions & { code: string }): RenderedCodeBlockData
  tokenize(code: string, options?: HighlightOptions): HighlightTokenResult
}

listLanguages returns canonical names, not aliases. normalizeLanguage returns a canonical name when registered and the configured fallback otherwise.

HighlightOptions

RenderCodeBlockOptions

HighlightOptions plus an optional title.

HighlightTokenResult

type HighlightTokenResult = {
  code: string
  lang: string
  tokens: Array<HighlightToken>
}

HighlightResult

HighlightTokenResult plus html, a complete escaped <pre><code> string.

RenderedCodeBlockData

type RenderedCodeBlockData = {
  copyText: string
  htmlMarkup: string
  lang: string
  title?: string
  tokens: Array<HighlightToken>
}

renderCodeBlockData trims trailing whitespace before creating every field.

Tokens

HighlightTokenClass

The semantic class union: attr, code-inline, command, comment, deleted, function, heading, inserted, keyword, link, literal, meta, number, operator, property, selector, string, tag, type, and variable.

HighlightToken

type HighlightToken = {
  className?: HighlightTokenClass
  value: string
}

Untyped source segments omit className. Concatenating every value always reconstructs the input exactly.

Decorations

HighlightDecorationData

Record<string, boolean | number | string>. Keys become escaped data-* attributes on rendered spans.

HighlightRangeDecoration

type HighlightRangeDecoration = {
  range: readonly [start: number, end: number]
  className?: string
  data?: HighlightDecorationData
}

The range uses zero-based, end-exclusive UTF-16 offsets.

HighlightLineDecoration

type HighlightLineDecoration = {
  lines: number | readonly [start: number, end: number]
  className?: string
  data?: HighlightDecorationData
}

Lines are one-based and an interval includes both ends.

HighlightDecoration

The union of HighlightLineDecoration and HighlightRangeDecoration. A decoration cannot contain both lines and range.

Render tree

HighlightTextNode

type HighlightTextNode = { type: 'text'; value: string }

HighlightElementNode

type HighlightElementNode = {
  type: 'element'
  classNames: Array<string>
  data?: Record<string, string>
  children: Array<HighlightRenderNode>
}

HighlightRenderNode

The union of HighlightTextNode and HighlightElementNode.

renderTokens

function renderTokens(
  tokens: ReadonlyArray<HighlightToken>,
  options?: Pick<HighlightOptions, 'decorations' | 'lineNumbers'>,
): Array<HighlightRenderNode>

Converts flat tokens to the renderer-neutral tree. It adds th-* token spans, decoration spans, and th-line wrappers when line numbers or line decorations require them.

renderNodesToHtml

function renderNodesToHtml(nodes: ReadonlyArray<HighlightRenderNode>): string

Serializes render nodes to escaped HTML.

escapeHtml

function escapeHtml(value: string): string

Escapes &, <, >, double quotes, and single quotes for HTML text output.