Zero-allocation terminal input key and mouse decoder in Go.
do not allocate on timeout, return a constant error value
support decoding multiple keys from one buffer, and load more if needed
notes for improvements



You can also use your local clone with git send-email.

#zzterm builds.sr.ht status GoDoc go.dev reference

Package zzterm efficiently reads and decodes terminal input keys and mouse events without any memory allocation. It is intended to be used with a terminal set in raw mode as its io.Reader. See the package documentation for details, API reference and usage example (alternatively, on pkg.go.dev).

You can also check out zztermtest for more usage examples and how to efficiently print output to an io.Writer (with a zero-allocation "echo" program example).

Note that at the moment, zzterm is only tested on macOS and linux. Mouse support is through the Xterm X11 mouse protocol with SGR enabled, the terminal has to support that mode for mouse (and focus) key events to be emitted.

#See Also

Similar Go packages:


The input processing is typically in the hot path of a terminal application. Zzterm is quite fast and does not allocate - not when decoding standard keys, not when decoding escape sequences, neither when decoding mouse events.

benchmark                                    iter     time/iter   bytes alloc        allocs
---------                                    ----     ---------   -----------        ------
BenchmarkInput_ReadKey/a-4               61804756   18.40 ns/op        0 B/op   0 allocs/op
BenchmarkInput_ReadKey/B-4               66716232   17.90 ns/op        0 B/op   0 allocs/op
BenchmarkInput_ReadKey/1-4               62950432   18.60 ns/op        0 B/op   0 allocs/op
BenchmarkInput_ReadKey/\x00-4            65492827   18.20 ns/op        0 B/op   0 allocs/op
BenchmarkInput_ReadKey/ø-4               60368734   19.90 ns/op        0 B/op   0 allocs/op
BenchmarkInput_ReadKey/👪-4              57783043   20.60 ns/op        0 B/op   0 allocs/op
BenchmarkInput_ReadKey/平-4              57067489   20.80 ns/op        0 B/op   0 allocs/op
BenchmarkInput_ReadKey/\x1b[B-4          26063134   45.90 ns/op        0 B/op   0 allocs/op
BenchmarkInput_ReadKey/\x1b[1;2C-4       26355364   45.40 ns/op        0 B/op   0 allocs/op
BenchmarkInput_ReadKey/\x1b[I-4          26530273   44.40 ns/op        0 B/op   0 allocs/op
BenchmarkInput_ReadKey/\x1b[<35;1;2M-4   21740397   55.30 ns/op        0 B/op   0 allocs/op
BenchmarkInput_ReadKey_Bytes-4           49141444   24.40 ns/op        0 B/op   0 allocs/op
BenchmarkInput_ReadKey_Mouse-4           19961526   60.70 ns/op        0 B/op   0 allocs/op


The BSD 3-Clause license.