Ultraviolet

Ultraviolet is a set of primitives for building terminal user interfaces in Go. It provides cell-based rendering, cross-platform input handling, and a diffing renderer inspired by ncurses—without the need for terminfo or termcap databases.

Ultraviolet powers Bubble Tea v2 and Lip Gloss v2. It replaces the ad-hoc terminal primitives from earlier versions with a cohesive, imperative API that can also be used standalone.

Install

go get github.com/charmbracelet/ultraviolet@latest

Quick Start

package main

import (
	"log"

	uv "github.com/charmbracelet/ultraviolet"
	"github.com/charmbracelet/ultraviolet/screen"
)

func main() {
	t := uv.DefaultTerminal()
	scr := t.Screen()

	scr.EnterAltScreen()

	if err := t.Start(); err != nil {
		log.Fatalf("failed to start terminal: %v", err)
	}
	defer t.Stop()

	ctx := screen.NewContext(scr)
	text := "Hello, World!"
	textWidth := scr.StringWidth(text)

	display := func() {
		screen.Clear(scr)
		bounds := scr.Bounds()
		x := (bounds.Dx() - textWidth) / 2
		y := bounds.Dy() / 2
		ctx.DrawString(text, x, y)
		scr.Render()
		scr.Flush()
	}

	for ev := range t.Events() {
		switch ev := ev.(type) {
		case uv.WindowSizeEvent:
			scr.Resize(ev.Width, ev.Height)
			display()
		case uv.KeyPressEvent:
			if ev.MatchString("q", "ctrl+c") {
				return
			}
		}
	}
}

Architecture

Ultraviolet is organized as a set of layered primitives:

• Terminal — manages the application lifecycle: raw mode, input event loop, start/stop. Create one with DefaultTerminal() or NewTerminal(console, opts).

• TerminalScreen — the screen state manager. Handles rendering, alternate screen buffer, cursor, mouse modes, keyboard enhancements, bracketed paste, window title, and more. Access it via terminal.Screen().

• Screen — a minimal interface (Bounds, CellAt, SetCell, WidthMethod) implemented by TerminalScreen, Buffer, Window, and ScreenBuffer. Write code against Screen to stay decoupled from the terminal.

• Buffer / Window — off-screen cell buffers. Buffer is a flat grid of cells. Window adds parent/child relationships and shared-buffer views. Both implement Screen and Drawable.

• screen package — drawing helpers that operate on any Screen: a Context for styled text rendering (Print, DrawString, etc.) and utility functions like Clear, Fill, Clone.

• layout package — a constraint-based layout solver built on the Cassowary algorithm. Partition screen space with Len, Min, Max, Percent, Ratio, and Fill constraints.

Features

• Cell-based diffing renderer — only redraws what changed. Optimizes cursor movement, uses ECH/REP/ICH/DCH when available, and supports scroll optimizations. Minimal bandwidth, critical for SSH.

• Universal input — unified keyboard and mouse event handling across platforms. Supports legacy encodings, Kitty keyboard protocol, SGR mouse, and Windows Console input.

• Inline and fullscreen — works in both alternate screen (fullscreen) and inline mode. Inline TUIs preserve terminal context and scrollback.

• Cross-platform — first-class support for Unix (termios + ANSI) and Windows (Console API). Consistent behavior across terminal emulators.

• Suspend/resume — Stop() and Start() can be called repeatedly for suspend/resume cycles, shelling out to editors, or process suspension via uv.Suspend().

Examples

See the examples/ directory for core examples and examples/advanced/ for more complex demos.

Tutorial

See TUTORIAL.md for a step-by-step guide to building your first Ultraviolet application.

Note

Ultraviolet is in active development. The API may change.

Feedback

We'd love to hear your thoughts on this project. Feel free to drop us a note!

• Twitter
• Discord
• Slack
• The Fediverse

License

MIT

---

Part of Charm.

Charm热爱开源 • Charm loves open source • نحنُ نحب المصادر المفتوحة