Diff

Diff renders one file patch in a unified or split view with syntax highlighting and optional line numbers. Use Code when you do not need patch parsing.

Availability#

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

Basic usage#

Renderable API#

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

const renderer = await createCliRenderer()

const syntaxStyle = SyntaxStyle.fromStyles({
  default: { fg: RGBA.fromHex("#E6EDF3") },
  string: { fg: RGBA.fromHex("#A5D6FF") },
  keyword: { fg: RGBA.fromHex("#FF7B72"), bold: true },
})

const patch = `diff --git a/app.ts b/app.ts
index 1111111..2222222 100644
--- a/app.ts
+++ b/app.ts
@@ -1,3 +1,3 @@
 setup()
-const a = 1
+const a = 2
 ready(a)
`

const diff = new DiffRenderable(renderer, {
  id: "diff",
  width: "100%",
  height: 16,
  diff: patch,
  view: "split",
  filetype: "typescript",
  syntaxStyle,
  showLineNumbers: true,
})

renderer.root.add(diff)

Monochrome views of the same patch:

Unified view:

 1   setup()     2 - const a = 1 2 + const a = 2 3   ready(a)

Split view:

 1   setup()      1   setup()      2 - const a = 1  2 + const a = 2  3   ready(a)     3   ready(a)

For multi-file input, Diff currently displays only patches[0]. Create one DiffRenderable for each file patch that you need to show.

Split view scroll sync#

When view: "split" is active, you can link scrollX and scrollY for both panes. Scrolling one pane then moves the other:

const diff = new DiffRenderable(renderer, {
  id: "diff",
  view: "split",
  syncScroll: true,
  diff: patch,
  syntaxStyle,
})

// Toggle at runtime
diff.syncScroll = false

Scroll sync is a no-op in the unified view.

Properties#

Property	Type	Default	Description
`diff`	`string`	`""`	Unified diff string
`view`	`"unified"` or `"split"`	`"unified"`	Layout style
`syncScroll`	`boolean`	`false`	Link horizontal and vertical scroll in split view
`filetype`	`string`	-	Syntax highlighting language
`fg`	`string` or `RGBA`	-	Base foreground for inner code panes
`syntaxStyle`	`SyntaxStyle`	-	Syntax style for code
`wrapMode`	`"word"`, `"char"`, or `"none"`	-	Code wrapping mode
`conceal`	`boolean`	`false`	Conceal markup when highlighting
`selectionBg`	`string` or `RGBA`	-	Selection background in code panes
`selectionFg`	`string` or `RGBA`	-	Selection foreground in code panes
`treeSitterClient`	`TreeSitterClient`	-	Custom Tree-sitter client
`showLineNumbers`	`boolean`	`true`	Show line numbers
`lineNumberFg`	`string` or `RGBA`	`#888888`	Line number text color
`lineNumberBg`	`string` or `RGBA`	transparent	Line number background
`addedLineNumberBg`	`string` or `RGBA`	transparent	Line number background for added
`removedLineNumberBg`	`string` or `RGBA`	transparent	Line number background for removed
`addedBg`	`string` or `RGBA`	`#1a4d1a`	Background for added lines
`removedBg`	`string` or `RGBA`	`#4d1a1a`	Background for removed lines
`contextBg`	`string` or `RGBA`	transparent	Background for context lines
`addedContentBg`	`string` or `RGBA`	-	Optional content background (added)
`removedContentBg`	`string` or `RGBA`	-	Optional content background (removed)
`contextContentBg`	`string` or `RGBA`	-	Optional content background (context)
`addedSignColor`	`string` or `RGBA`	`#22c55e`	Sign color for added lines
`removedSignColor`	`string` or `RGBA`	`#ef4444`	Sign color for removed lines

Other grammars require Tree-sitter configuration. See the Tree-sitter reference.

Use Code for source text without patch structure. Use Line number gutter with other line-aware renderables. Use Markdown for documents and TextTable for general tabular comparisons.