Syntax Highlighting

Syntax highlighting API for applying color and text attributes to code in terminal UIs

Overview

The Syntax Highlighting API provides a high-performance system for styling text with colors and attributes (bold, italic, underline, dim) in terminal applications. It’s designed for syntax highlighting but can be used for any text styling needs.

SyntaxStyle Class

SyntaxStyle.create()

Creates a new syntax style instance.

import { SyntaxStyle } from "@opentui/core"

const style = SyntaxStyle.create()

style · SyntaxStyle

A new SyntaxStyle instance

SyntaxStyle.fromTheme()

Creates a syntax style from a theme definition.

const style = SyntaxStyle.fromTheme([
  {
    scope: ["keyword", "keyword.control"],
    style: {
      foreground: "#FF0000",
      bold: true
    }
  },
  {
    scope: ["string"],
    style: {
      foreground: { r: 0, g: 1, b: 0, a: 1 },
      italic: true
    }
  }
])

theme · ThemeTokenStyle[] · required

Array of theme token styles

Show ThemeTokenStyle properties

scope · string[] · required

Array of scope names this style applies to

style · object · required

Style definition

Show style properties

foreground · ColorInput

Foreground color as hex string or RGBA object

background · ColorInput

Background color as hex string or RGBA object

bold · boolean

Apply bold attribute

italic · boolean

Apply italic attribute

underline · boolean

Apply underline attribute

dim · boolean

Apply dim attribute

style · SyntaxStyle

A new SyntaxStyle instance with registered theme styles

SyntaxStyle.fromStyles()

Creates a syntax style from a flat style definition object.

const style = SyntaxStyle.fromStyles({
  keyword: {
    fg: RGBA.fromValues(1, 0, 0, 1),
    bold: true
  },
  string: {
    fg: RGBA.fromValues(0, 1, 0, 1),
    italic: true
  },
  comment: {
    fg: RGBA.fromValues(0.5, 0.5, 0.5, 1),
    dim: true
  }
})

styles · Record<string, StyleDefinition> · required

Object mapping style names to style definitions

style · SyntaxStyle

A new SyntaxStyle instance with registered styles

Instance Methods

registerStyle()

Registers a new style with a given name.

const styleId = style.registerStyle("function.name", {
  fg: RGBA.fromValues(0, 0.5, 1, 1),
  bold: true,
  underline: true
})

name · string · required

Unique name for this style

style · StyleDefinition · required

Style definition

Show StyleDefinition properties

fg · RGBA

Foreground color

bg · RGBA

Background color

bold · boolean

Bold text

italic · boolean

Italic text

underline · boolean

Underlined text

dim · boolean

Dimmed text

styleId · number

Numeric ID for the registered style

resolveStyleId()

Resolves a style name to its numeric ID.

const id = style.resolveStyleId("keyword")
// Returns: 1 (or null if not found)

name · string · required

Name of the style to resolve

id · number | null

Numeric style ID, or null if not found

getStyleId()

Gets a style ID by name, with fallback to base scope for dotted names.

// If "keyword.control" is not registered, falls back to "keyword"
const id = style.getStyleId("keyword.control")

name · string · required

Name of the style (supports dot notation like “keyword.control”)

id · number | null

Numeric style ID, or null if not found

getStyle()

Retrieves a style definition by name.

const styleDef = style.getStyle("keyword")
// Returns: { fg: RGBA, bold: true }

name · string · required

Name of the style to retrieve

style · StyleDefinition | undefined

The style definition, or undefined if not found

mergeStyles()

Merges multiple styles together, with later styles overriding earlier ones.

const merged = style.mergeStyles("keyword", "keyword.control", "emphasis")
// Returns: { fg: RGBA, bg: RGBA, attributes: number }

...styleNames · string[] · required

Names of styles to merge (later styles override earlier ones)

merged · MergedStyle

Merged style with combined colors and attributes

Show MergedStyle properties

fg · RGBA | undefined

Merged foreground color

bg · RGBA | undefined

Merged background color

attributes · number

Combined text attributes as bit flags

getAllStyles()

Gets all registered style definitions.

const allStyles = style.getAllStyles()
// Returns: Map<string, StyleDefinition>

styles · Map<string, StyleDefinition>

Map of all registered styles

getRegisteredNames()

Gets all registered style names.

const names = style.getRegisteredNames()
// Returns: ["keyword", "string", "comment", ...]

names · string[]

Array of all registered style names

getStyleCount()

Gets the total number of registered styles.

const count = style.getStyleCount()
// Returns: 42

count · number

Number of registered styles

clearCache()

Clears the internal merged styles cache.

style.clearCache()

clearNameCache()

Clears the name-to-ID resolution cache.

style.clearNameCache()

getCacheSize()

Gets the current size of the merged styles cache.

const size = style.getCacheSize()
// Returns: 15

size · number

Number of cached merged style combinations

destroy()

Destroy the style instance and free resources.

style.destroy()

Utility Functions

convertThemeToStyles()

Converts a theme token array to a flat styles object.

import { convertThemeToStyles } from "@opentui/core"

const theme = [
  {
    scope: ["keyword", "keyword.control"],
    style: { foreground: "#FF0000", bold: true }
  }
]

const flatStyles = convertThemeToStyles(theme)
// Returns: { keyword: { fg: RGBA, bold: true }, "keyword.control": { ... } }

theme · ThemeTokenStyle[] · required

Theme definition array

styles · Record<string, StyleDefinition>

Flat object mapping scope names to style definitions

Types

ColorInput

Color can be specified as a hex string or RGBA object:

type ColorInput = string | { r: number; g: number; b: number; a: number }

// Examples:
"#FF0000"
"#FF0000FF"
{ r: 1.0, g: 0.0, b: 0.0, a: 1.0 }

RGBA

Color object with normalized values (0-1 range):

import { RGBA } from "@opentui/core"

const red = RGBA.fromValues(1, 0, 0, 1)
const blue = RGBA.fromHex("#0000FF")

Example: Syntax Highlighting

import { SyntaxStyle, RGBA } from "@opentui/core"

// Create a style for TypeScript syntax
const tsStyle = SyntaxStyle.fromStyles({
  keyword: {
    fg: RGBA.fromHex("#C586C0"),
    bold: true
  },
  "keyword.control": {
    fg: RGBA.fromHex("#C586C0"),
    italic: true
  },
  string: {
    fg: RGBA.fromHex("#CE9178")
  },
  "string.template": {
    fg: RGBA.fromHex("#CE9178")
  },
  number: {
    fg: RGBA.fromHex("#B5CEA8")
  },
  comment: {
    fg: RGBA.fromHex("#6A9955"),
    italic: true
  },
  function: {
    fg: RGBA.fromHex("#DCDCAA")
  },
  variable: {
    fg: RGBA.fromHex("#9CDCFE")
  },
  type: {
    fg: RGBA.fromHex("#4EC9B0")
  }
})

// Use the style
const keywordId = tsStyle.getStyleId("keyword")
const merged = tsStyle.mergeStyles("keyword", "keyword.control")

// Clean up when done
tsStyle.destroy()