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. The initial call has depth zero; delegated calls beyond depth 24 return no token ranges.

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 a highlighter with name and alias maps from the supplied registrations. There is no method for adding registrations later. The returned object and language definitions are not frozen; keep shared definitions unchanged.

The default fallback name is plaintext. Unknown language names resolve to the configured fallback and use its tokenizer if registered. An unregistered fallback produces escaped plain text under that fallback name.

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 applies code.trimEnd() before generating copyText, htmlMarkup, and tokens. It preserves the supplied title and normalizes lang.

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 reconstructs the string passed to tokenization. For block-data and fence helpers, that string has already had trailing whitespace removed.

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. Both offsets must be integers with start < end; otherwise the decoration is ignored. Ranges extending outside the source are clipped to its bounds.

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.