---

title: Line number gutter description: Add a line number gutter to code and editor renderables

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") },
})

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

Line signs and colors

Set a single background for a line, or split gutter and content colors separately 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 darkened by 20%. A LineColorConfig with only gutter uses the same darkening rule.

Theming the gutter

Gutter text and background colors accept assignments after construction:

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

Assign undefined to reset to the defaults (#888888 foreground, transparent background).

Initial visibility

The constructor currently ignores the showLineNumbers option. Set the property after construction when the initial gutter must be hidden:

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.