Renders time-series and financial data as interactive charts with multiple styles.

Supported chart types: :line, :braille, :step, :area, :braille_area, :bar, :clustered_bar, :stacked_bar, :range_bar, :scatter, :bubble, :histogram, :heatmap, and :candlestick. Any unrecognised value renders as :line. Braille-dot rendering provides the highest resolution (two data points per column, four per row). Quadrant-block rendering provides 2×2 pixel resolution per cell (coarser but larger dots). Bar charts use half-block characters for 2× vertical resolution.

Each chart type reads :data in its own shape:

• :line, :braille, :step, :area, :braille_area, :bar — a list of numbers, or a list of such lists for multiple series
• :clustered_bar, :stacked_bar — a list of series, each a list of numbers
• :range_bar — a list of [low, high] pairs, one per bar
• :scatter — [x, y] lists, {x, y} tuples, or weighted variants [x, y, weight] / {x, y, weight} where weight is a float between 0.0 and 1.0. Higher weights produce denser braille dot clusters and brighter colors. A list of point-lists renders multiple series
• :bubble — points carrying a magnitude, rendered as sized dots; a list of point-lists renders multiple series
• :histogram — a flat list of raw values, binned automatically
• :heatmap — a list of rows, each a list of numbers, forming a matrix
• :candlestick — [open, high, low, close] lists or maps with :open, :high, :low, :close keys

Component tag

Tag :chart, built by Drafter.App as {:chart, data, opts}:

chart(data, opts)

The positional argument becomes :data when it is a list; otherwise :data is read from opts. Because a bare keyword list in the first position is treated as opts, both chart(values, chart_type: :line) and chart(data: values, chart_type: :line) are valid. :width and :height default to the rect the parent allocated.

Negative Values

All chart types (except candlestick) support negative values natively. The Y-axis range is derived from the data including any negative values. For charts that span both positive and negative territory a zero-line is drawn automatically when show_axes: true. Set min_value and max_value explicitly to pin a symmetric range:

chart(io_data, chart_type: :line, min_value: -150, max_value: 150, show_axes: true)

Multi-Series Charts

Pass a list of series (each a list of values) to :data for :line, :clustered_bar, :stacked_bar, and :scatter. Each series is rendered in its own colour cycling through :colors. If :colors is empty a built-in palette of six hues is used.

chart([series_a, series_b, series_c],
  chart_type: :line,
  height: 8,
  colors: [{100, 200, 255}, {255, 150, 80}, {80, 255, 150}]
)

For :scatter, multi-series data is a list of point-lists where each point-list contains [x, y] pairs:

chart([series_a_points, series_b_points], chart_type: :scatter, height: 8)

For :range_bar, data is a list of [low, high] pairs — one pair per bar:

chart([[10, 40], [25, 65], [5, 55]], chart_type: :range_bar, height: 8)

Bar Chart Types

• :bar — classic single-row sparkline; one block-char per data point
• :clustered_bar — multi-row grouped bars; each group shows one bar per series side by side with half-block vertical resolution
• :stacked_bar — multi-row stacked bars; series accumulate from the baseline (supports negatives — positive series stack upward, negative series stack downward)
• :range_bar — one bar per data point spanning a low→high range

Keyboard Controls (when focused)

• ← / → — scroll the X-axis by 5 data points, clamped at 0 on the left
• ↑ / ↓ — pan the Y-axis up/down by 1 unit
• ?c — reset the Y-axis pan offset to 0
• Click and drag — pan both axes simultaneously

Every other key bubbles.

Options

• :data — numeric list; list of series for multi-series types; [low, high] pairs for :range_bar. Default []
• :chart_type — :line (default), :step, :area, :braille, :braille_area, :bar, :clustered_bar, :stacked_bar, :range_bar, :scatter, :bubble, :histogram, :heatmap, :candlestick. Any other value renders as :line
• :pixel_style — pixel rendering style for line, step and scatter: :braille (default) or :quadrant
• :min_value — explicit Y minimum. Default nil, auto-detected from the data with 5% padding on each side
• :max_value — explicit Y maximum. Default nil, auto-detected from the data with 5% padding on each side. When the resolved minimum equals the maximum the range is widened by 0.001 either way
• :color — {r, g, b} primary colour for single-series charts. Default nil, falling back to the theme and then to {100, 200, 255}
• :colors — list of {r, g, b} tuples, one per series for multi-series types; the first entry overrides :color for single-series bar/scatter/area. Default []
• :show_axes — boolean/0, draw axis lines and the zero-line when the range spans zero. Default false. Reserves two rows and a labelled left column
• :show_labels — boolean/0, draw axis tick labels. Default false
• :title — String.t/0 displayed on a row above the chart. Default nil; an empty string is treated the same as nil
• :x_labels — list of strings for X-axis tick labels. Default []
• :y_labels — list of strings for Y-axis tick labels. Default []
• :orientation — :vertical (default) or :horizontal; applies to :bar, :clustered_bar, :stacked_bar and :range_bar only, and every other chart type falls back to the vertical renderer
• :bar_labels — list of strings labelling each bar or group, shown when show_labels: true. Default []
• :show_values — boolean/0, show the numeric value beside each bar. Default false
• :fill_opacity — brightness of the area fill body relative to the series colour, 0.0 (invisible) to 1.0 (same as edge). Default 0.6
• :animated — boolean/0, animate new data points. Default false
• :animation_speed — milliseconds per animation frame. Default 100
• :width — chart width in columns. The element defaults it to the rect the parent allocated, but rendering always uses rect.width, so this only reaches the state
• :height — chart height in rows. The element defaults it to the rect the parent allocated; mount/1 on its own defaults it to 1
• :max_data_points — cap on retained points; older points are dropped when exceeded. Default nil, no cap
• :bar_gap — blank columns between bars. Default 0
• :area_fill — which side of the line the area body fills: :below (default) or :inverted to fill from the line up to the top edge
• :show_baseline — boolean/0, draw the zero baseline row on stacked braille areas. Default false
• :zero_center — how a stacked range spanning zero is scaled: :symmetric (default, equal extent either side of zero) or :independent to let the positive and negative extents differ. Ignored when the data does not cross zero
• :smooth — boolean/0, interpolate between points on line charts. Default false
• :line_thickness — line width in pixels for line and area charts. Default 1
• :connect_lines — boolean/0, join consecutive points with line segments. Default false
• :raw_data — boolean/0, plot every point instead of downsampling to the viewport width with LTTB. Default false
• :precision — decimal places in the Y-axis tick labels. Default 3. Read by mount/1 and update/2 only; the chart/2 element does not forward it
• :style — map/0 of style properties. Default %{}
• :class — theme class atom or list of them, reaching mount/1 as :classes. Default []
• :renderer — rendering backend for this chart: :text (ASCII/block), :braille (anti-aliased braille), :pixel / :auto (best terminal graphics available — kitty/iTerm2/sixel image, falling back to braille), or :iterm2 / :kitty / :sixel to force a protocol. Overrides the runtime mode: config, but the DRAFTER_MODE env var still forces over it. When unset, the global mode applies: DRAFTER_MODE, then the mode: run option (Drafter.run(App, mode: :pixel) / Drafter.render_mode/1), then :text.
• :image_throttle — for :pixel charts, the minimum gap between image regenerations, in Drafter's timing units: {n, :fps}, {n, :ms}, {n, :tick} (every n render frames — the default, frame-aligned so it can't beat against the render clock), or a bare integer (milliseconds). Default {2, :tick}. Lower means smoother animation but more terminal load.
• :image_scale — for :pixel charts, pixels generated per terminal cell column (rows use 2×); default 4. Higher is sharper but produces larger images.

update/2 re-reads every option above except :width, :app_module and :image_throttle, which are fixed once the widget is mounted.

Widget value

Drafter.get_widget_value/1 is not implemented for this widget and returns nil.

Usage

chart(data: [1, 4, 2, 8, 5, 9, 3], chart_type: :line)
chart(data: candles, chart_type: :candlestick, show_axes: true)
chart(data: points, chart_type: :scatter)
chart(data: [series_a, series_b], chart_type: :clustered_bar, height: 8)
chart(data: [series_a, series_b], chart_type: :stacked_bar, height: 8)
chart(data: [[lo, hi] | ...], chart_type: :range_bar, height: 8)
chart(data: io_data, chart_type: :line, min_value: -150, max_value: 150)