These docs describe the main branch, including unreleased changes. Read the 0.6.0 docs.

Line number gutter

LineNumberRenderable adds a gutter to a renderable that supplies line information. Use it with Code or an editor. Diff manages its own line-number gutters.

Availability#

Field	Availability
Package	`@opentui/core`
Core renderable	`LineNumberRenderable`
React	`<line-number>` (automatic)
Solid	`<line_number>` is runtime built in. Its exact props declaration is missing.
Status	Built in with a Solid typing limitation

Basic usage#

Renderable API#

import {
  CodeRenderable,
  LineNumberRenderable,
  ScrollBoxRenderable,
  SyntaxStyle,
  RGBA,
  createCliRenderer,
} from "@opentui/core"

const renderer = await createCliRenderer()

const syntaxStyle = SyntaxStyle.fromStyles(
  {
    default: { fg: RGBA.fromHex("#E6EDF3") },
  },
  renderer.nativeScene,
)

const code = new CodeRenderable(renderer, {
  id: "code",
  content: "const port = 3000\nserve(port)\nawait ready()",
  filetype: "typescript",
  syntaxStyle,
  width: "100%",
})

const lineNumbers = new LineNumberRenderable(renderer, {
  id: "code-lines",
  target: code,
  minWidth: 3,
  paddingRight: 1,
  fg: "#6b7280",
  bg: "#161b22",
})

const scrollbox = new ScrollBoxRenderable(renderer, {
  id: "scrollbox",
  width: 70,
  height: 18,
})

lineNumbers.setLineSign(1, { before: ">" })
scrollbox.add(lineNumbers)
renderer.root.add(scrollbox)

  1 const port = 3000   > 2 serve(port)           3 await ready()

LineNumberRenderable adds the gutter and the target as its own children. Add the LineNumberRenderable to the tree, not the target.

Line signs and colors#

Line arguments and map keys are zero-based logical line indexes. With the default lineNumberOffset, line 0 shows the number 1.

Set one background color for a line, or set separate gutter and content colors with a LineColorConfig object:

// Shorthand: applies the color to the gutter and a 20%-darker color to the content
lineNumbers.setLineColor(3, "#2b6cb0")

// Split config: different gutter vs content background
lineNumbers.setLineColor(3, {
  gutter: "#2b6cb0",
  content: "#1f2937",
})

lineNumbers.setLineSign(3, { before: ">", beforeColor: "#2b6cb0" })

// Clear
lineNumbers.clearLineColor(3)
lineNumbers.clearLineSign(3)

The shorthand color becomes the gutter background. The content background uses the same color, 20% darker. A LineColorConfig with only gutter uses the same rule for the content background.

Theming the gutter#

You can change the gutter text and background colors after construction:

lineNumbers.fg = "#6b7280"
lineNumbers.bg = "#161b22"

Assign undefined to restore the defaults: a #888888 foreground and a transparent background.

Initial visibility#

The constructor ignores the showLineNumbers option. To hide the gutter at the start, set the property after construction:

const lineNumbers = new LineNumberRenderable(renderer, { target: code })
lineNumbers.showLineNumbers = false

Properties#

Property	Type	Default	Description
`target`	`Renderable & LineInfoProvider`	-	Target renderable to number
`fg`	`string` or `RGBA`	`#888888`	Gutter text color
`bg`	`string` or `RGBA`	transparent	Gutter background color
`minWidth`	`number`	`3`	Minimum gutter width
`paddingRight`	`number`	`1`	Right padding for gutter
`lineColors`	`Map<number, string \| RGBA \| LineColorConfig>`	-	Per-line background colors
`lineSigns`	`Map<number, LineSign>`	-	Per-line signs (before/after)
`lineNumberOffset`	`number`	`0`	Offset for line numbering
`hideLineNumbers`	`Set<number>`	-	Lines to hide numbers for
`lineNumbers`	`Map<number, number>`	-	Override line numbers per line
`showLineNumbers`	`boolean`	`true`	Toggle gutter visibility

Methods#

Method	Description
`setLineColor()`	Set a background color for a line
`clearLineColor()`	Clear a line background color
`setLineSign()`	Set a sign before/after a line number
`clearLineSign()`	Clear a line sign
`setLineNumbers()`	Override multiple line numbers
`setHideLineNumbers()`	Hide line numbers for specific lines

Use Code as a syntax-highlighted target. Use Diff when you need patch parsing and paired gutters. Markdown owns fenced code blocks. TextTable displays rows and columns without line semantics.