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.

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.