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

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

Methods

Related components

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.