# 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](https://invisible-island.net/ncurses/)—without
the need for `terminfo` or `termcap` databases.
Ultraviolet powers [Bubble Tea v2][bbt] and [Lip Gloss v2][lg]. It replaces the
ad-hoc terminal primitives from earlier versions with a cohesive, imperative API
that can also be used standalone.
[bbt]: https://github.com/charmbracelet/bubbletea
[lg]: https://github.com/charmbracelet/lipgloss
## Install
```bash
go get github.com/charmbracelet/ultraviolet@latest
```
## Quick Start
```go
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][casso]. Partition screen space with `Len`, `Min`,
`Max`, `Percent`, `Ratio`, and `Fill` constraints.
[casso]: https://en.wikipedia.org/wiki/Cassowary_(software)
## 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/`](./examples/) directory for core examples and
[`examples/advanced/`](./examples/advanced/) for more complex demos.
## Tutorial
See [TUTORIAL.md](./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](https://twitter.com/charmcli)
- [Discord](https://charm.land/discord)
- [Slack](https://charm.land/slack)
- [The Fediverse](https://mastodon.social/@charmcli)
## License
[MIT](./LICENSE)
---
Part of [Charm](https://charm.land).
Charm热爱开源 • Charm loves open source • نحنُ نحب المصادر المفتوحة