ntcharts draws terminal charts as Bubble Tea models

ntcharts puts charts inside the Bubble Tea event loop

ntcharts is a Golang terminal charting library for the Bubble Tea framework and other TUIs. The problem it addresses is narrow and real: a terminal application built on Bubble Tea usually renders tables, forms and status text, and the moment a developer wants a graph they are left writing a plotting layer by hand. ntcharts supplies that layer as a set of Bubble Tea models, so a chart lives in the same program, reacts to the same key and mouse events, and is styled with the same border and colour tooling the rest of the interface uses. The dependency set in the module file shows the intended stack: charm.land/bubbletea/v2, charm.land/bubbles/v2 and charm.land/lipgloss/v2 for the framework and styling, lrstanley/bubblezone/v2 for mouse handling, golang.org/x/image for image work, and NimbleMarkets/pixterm. If your team already ships Go terminal apps, that audience is you.

Every chart type sits on one 2D rune canvas

The chart catalogue is broad but it rests on a single primitive. Canvas is described as a 2D grid to plot arbitrary runes, with LipGloss for styling and BubbleZone for mousing, and it is called the foundation for all the following charts. That is the design decision worth understanding before choosing the library. Bar charts, heat maps, line charts, scatter plots, time series charts, wavelines and sparklines are ways of placing runes on that grid rather than separate rendering engines. On top of it sit a bar chart with horizontal rows or vertical columns, a heat map that maps x and y values onto colour, an OHLC and candlestick view of open, high, low and close numbers, a scatter chart for arbitrary runes at x,y coordinates, a chart that carries a continuous line across the canvas from the right side to the left, and a time series chart that puts values on the y axis and time on the x axis. The practical consequence is that a shape you can picture as pixels but not as cells may still be drawable, since the grid accepts any rune at any coordinate.

Kitty graphics add a second rendering path with glyph fallback

Images are the part of ntcharts that does not go through the rune grid. The project lists a Picture model for embedded images and pictureurl for images fetched over http, plus a chart picture model that renders output from the go-analyze/charts project through an embedded picture.Model using Kitty graphics with a glyph fallback. A heat picture model does the same for continuous fields, is sampler driven, and in Kitty mode samples at full pixel resolution for smooth gradients. Terminal support is the catch here. A separate KITTY.md covers Kitty graphics in games, boards, tile maps and other coordinate aligned interfaces, and it includes instructions for running inside tmux. The lorem picsum demo needs a Kitty-graphics-capable terminal for its right pane, and the perlin noise demo cycles a sampling factor with the F key. The difference between a coarse glyph rendering and a smooth gradient is therefore a terminal capability you either have or do not.

One spec value can target the terminal and the web

The spec package is the newest idea in the layout and it changes what the library is for. It defines a neutral, surface-agnostic chart specification: a single spec.Spec value can be rendered to the terminal through spec.Build(s), which produces an ntcharts model, or to the web through echarts.ToECharts(s), which produces a go-echarts/v2 chart. The same data description then travels to a terminal dashboard and a browser dashboard without a second chart definition. The tree carries a spec/README.md, and the example directory includes combo-categorical and combo-timeseries-bar folders, which suggests the specification covers combined series rather than single charts only. Sibling projects widen the scope further: ntcharts-pdf for a terminal PDF viewer, ntcharts-svg for SVG viewing and vector export, ntcharts-osm for map tiles with markers and paths, and ntcharts3d for three dimensional charts with an orbit, pan and zoom camera. Each of those is described as building on ntcharts/v2/picture.

Adding the v2 module path and building the demo binaries

ntcharts is a Go module, so installation happens through your own module file. The module path is shown at the top of the module file in the repository:

module github.com/NimbleMarkets/ntcharts/v2

That file requires go 1.26.8 and pins the framework libraries at charm.land/bubbletea/v2 v2.0.10, charm.land/bubbles/v2 v2.2.1 and charm.land/lipgloss/v2 v2.0.6. Add the import path to your own go.mod and resolve it with the dependency workflow you already use, because no separate install script or binary distribution is documented. For a first look, standalone CLI demos are included, and the demo section states that running task builds them all into the bin directory:

task

The resulting commands include ntcharts-quickstart, which reproduces the tutorial time series chart with two data sets and mouse support, ntcharts-ohlc, which renders OHLC candles and a sparkline from a CSV file, ntcharts-picture for a two pane image demo, ntcharts-chartpicture for a live updating chart where r swaps line and bar, t cycles themes and g toggles modes, and ntcharts-heatpicture-perlin for an animated noise field where space starts and stops the animation and F cycles the sampling factor.

No GitHub releases and CSV driven demo data

Two limits deserve attention before you commit. The first is release hygiene. The repository has no GitHub releases, so there is no published artifact list to track and no release notes to read, even though a CHANGELOG.md sits in the top level of the tree. Upgrade planning depends instead on the module path, which carries a /v2 suffix, on the default branch named v2, and on how quickly you can absorb upstream movement in the charm.land packages. Some dependencies are pinned to released versions while others are pseudo-versions tied to individual upstream commits, for example charmbracelet/ultraviolet v0.0.0-20260928045949-bbf040aedf25, which means those entries follow upstream commits rather than tagged releases. The second limit is data input. The financial demo reads its candles from a CSV file bundled in the repository, and the picture demo fetches an image over http. ntcharts supplies rendering, not acquisition, so a dashboard that must pull a live market feed or query a database needs that layer built on top.

Where plain runes or a browser chart is the better answer

Two situations call for something else. If you need a chart embedded in a web page rather than a terminal, the spec package names go-echarts/v2 as the web target, so a browser renderer with its own tooltip and zoom behaviour is the alternative with more capability. If you need publication quality raster output, the chart picture model routes through go-analyze/charts, which produces an image, and the sibling ntcharts-svg project offers SVG and PNG export. On the terminal side the honest comparison is not another charting library but plain text. A bar chart drawn with block runes costs nothing in dependencies and stays readable over ssh on a terminal with no colour support. ntcharts earns its dependency weight when you need continuous redraw, mouse interaction, colour mapping or Kitty resolution, and loses to a dozen lines of runes when you only need a static sparkline.

Editorial conclusion

Adopt ntcharts when the deliverable is an interactive terminal program that already runs on Bubble Tea and needs charts that redraw and respond to the mouse. Do not adopt it for web dashboards, live market feeds or artefacts you need to hand to a designer. Before starting, check that your target terminal supports the Kitty graphics path if you plan to use picture, chartpicture or heatpicture, and pin the charm.land dependency versions in your own go.mod because the project publishes no GitHub releases to upgrade from.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. NimbleMarkets/ntcharts on GitHub
4. Project website
5. README