ntcharts

ntcharts - Nimble Terminal Charts

ntcharts is a Golang Terminal Charting library for the Bubble Tea Framework and other TUIs.

We supply many chart types within the glory of your terminal!

Quickstart Tutorial

This tutorial creates a simple Time Series Chart with two data sets utilizing the Bubble Tea framework, Lip Gloss for styling and BubbleZone for mouse support.

Demo Apps

Standalone CLI demos. Run task to build them all into the bin/ directory.

BubbleTea Version Compatibility

We have migrated to Bubble Tea v2. It exists on the v2 branch. You should import as so:

import "github.com/NimbleMarkets/ntcharts/v2"

Our Bubble Tea v1 compatible library exists on the main branch. You should import it as so:

import "github.com/NimbleMarkets/ntcharts"

We will continue to backport relevant fixes to both branches.

Please note that the v2 designation is for BubbleTea API compatibility. Despite the version number, the ntcharts API is still subject to change. v2 is the primary development branch branch now.

Usage

See the examples folder for code samples and visuals of each type.

Canvas

package main

import (
    "fmt"
    "github.com/NimbleMarkets/ntcharts/v2/canvas"
    "charm.land/lipgloss/v2"
)

func main() {
    c := canvas.New(5, 2)
    c.SetLinesWithStyle(
        []string{"hello", "world"},
        lipgloss.NewStyle().Foreground(lipgloss.Color("6"))) // cyan

    fmt.Println(c.View())
}

This example produces the following canvas with Lip Gloss foreground color:

Bar Chart

package main

import (
    "fmt"
    "github.com/NimbleMarkets/ntcharts/v2/barchart"
    "charm.land/lipgloss/v2"
)

func main() {
    d1 := barchart.BarData{
        Label: "A",
        Values: []barchart.BarValue{
            {"Item1", 21.2, lipgloss.NewStyle().Foreground(lipgloss.Color("10"))}}, // green
    }
    d2 := barchart.BarData{
        Label: "B",
        Values: []barchart.BarValue{
            {"Item1", 15.2, lipgloss.NewStyle().Foreground(lipgloss.Color("9"))}}, // red
    }

    bc := barchart.New(11, 10)
    bc.PushAll([]barchart.BarData{d1, d2})
    bc.Draw()

    fmt.Println(bc.View())
}

This example produces the following bar chart with green and red bars:

Streamline Chart

package main

import (
    "fmt"
    "github.com/NimbleMarkets/ntcharts/v2/linechart/streamlinechart"
)

func main() {
    slc := streamlinechart.New(13, 10)
    for _, v := range []float64{4, 6, 8, 10, 8, 6, 4, 2, 0, 2, 4} {
        slc.Push(v)
    }
    slc.Draw()

    fmt.Println(slc.View())
}

This example produces the following streamline chart:

  │  ╭╮      
 8│  ││      
  │ ╭╯╰╮     
 6│ │  │     
  │╭╯  ╰╮    
 4├╯    ╰╮  ╭
  │      │  │
 2│      ╰╮╭╯
  │       ││ 
 0│       ╰╯ 

Time Series Chart

package main

import (
    "fmt"
    "time"
    "github.com/NimbleMarkets/ntcharts/v2/linechart/timeserieslinechart"
)

func main() {
    tslc := timeserieslinechart.New(41, 10)
    for i, v := range []float64{0, 4, 8, 10, 8, 4, 0, -4, -8, -10, -8, -4, 0} {
        date := time.Now().Add(time.Hour * time.Duration(24*i))
        tslc.Push(timeserieslinechart.TimePoint{date, v})
    }
    tslc.DrawBraille()

    fmt.Println(tslc.View())
}

This example produces the following time series chart using braille runes starting with today's date:

 10│      ⣀⠤⠒⠉⠒⠤⡀                        
   │    ⡠⠊      ⠈⠢⡀                      
  5│  ⡠⠊          ⠈⠢⡀                    
   │⡠⠊              ⠈⠑⢄                 ⢀
  0│                   ⠑⡄              ⡔⠁
   │                    ⠈⠢⡀          ⡠⠊  
 -5│                      ⠈⠢⡀      ⡠⠊    
   │                        ⠈⠑⠢⢄⡠⠔⠊      
-10└─────────────────────────────────────
   '24 03/27   03/31   04/03   04/05     

Waveline Chart

package main

import (
    "fmt"
    "github.com/NimbleMarkets/ntcharts/v2/canvas"
    "github.com/NimbleMarkets/ntcharts/v2/linechart/wavelinechart"
)

func main() {
    wlc := wavelinechart.New(12, 10, wavelinechart.WithYRange(-3, 3))
    wlc.Plot(canvas.Float64Point{1.0, 2.0})
    wlc.Plot(canvas.Float64Point{3.0, -2.0})
    wlc.Plot(canvas.Float64Point{5.0, 2.0})
    wlc.Plot(canvas.Float64Point{7.0, -2.0})
    wlc.Plot(canvas.Float64Point{9.0, 2.0})
    wlc.Draw()

    fmt.Println(wlc.View())
}

This example produces the following waveline chart:

 3│         
  │╭╮  ╭╮  ╭
 2│││  ││  │
  │││  ││  │
 0├╯╰╮╭╯╰╮╭╯
  │  ││  ││ 
-2│  ││  ││ 
  │  ╰╯  ╰╯ 
-3└─────────
  0 2 4 6    

Sparkline

package main

import (
    "fmt"
    "github.com/NimbleMarkets/ntcharts/v2/sparkline"
)

func main() {
    sl := sparkline.New(10, 5)
    sl.PushAll([]float64{7.81, 3.82, 8.39, 2.06, 4.19, 4.34, 6.83, 2.51, 9.21, 1.3})
    sl.Draw()

    fmt.Println(sl.View())
}

This example produces the following sparkline:

Heat Map

Heat Maps map values to colors on a 2D grid. The following example creates a heatmap of the function sin(sqrt(x^2 + y^2)). There are more examples in the examples README.

package main

import (
	"fmt"
	"math"

	"github.com/NimbleMarkets/ntcharts/v2/heatmap"
)

func main() {
	hm := heatmap.New(20, 20, heatmap.WithValueRange(0, 1))
	hm.SetXYRange(-1, 1, -1, 1)
	for x := float64(-1); x < 1.0; x += 1.0 / float64(hm.GraphWidth()) {
		for y := float64(-1); y < 1.0; y += 1.0 / float64(hm.GraphHeight()) {
			val := math.Sin(math.Sqrt(x*x + y*y))
			hm.Push(heatmap.NewHeatPoint(x, y, val))
		}
	}
	hm.Draw()
	fmt.Println(hm.View())
}

This example (source) produces the following heatmap:

Open Collaboration

We welcome contributions and feedback. Please adhere to our Code of Conduct when engaging our community.

• GitHub Issues
• GitHub Pull Requests

Acknowledgements

Thanks to Charm.sh for making the command line glamorous and sharing Bubble Tea and Lip Gloss and more. Thanks to BubbleZone for bringing the mouse support 🐭.

Thanks also to asciigraph, ratatui, and termdash for inspiration.

License

Released under the MIT License, see LICENSE.txt.

The image [`./examples/picture/Fuji-01.png] is from this link and licensed under Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.

Copyright (c) 2024-2026 Neomantra Corp.

Made with ❤ and 🔥 by the team behind Nimble.Markets.