Skip to main content

​
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
​
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
​
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

​
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()

Build docs developers (and LLMs) love

Get started for freeTalk to us