ChartSpec configuration reference

ChartSpec is the configuration object you pass to new Taucharts.Chart() (or new Taucharts.Plot()). It describes what data to render, which chart type to use, how fields map to visual channels, and how the chart should behave. Every field except type and data is optional, but in practice x, y, and data are nearly always required.

Top-level fields

type

string

required

The chart type to render. Must be one of:

'bar'
'horizontal-bar'
'horizontal-stacked-bar'
'line'
'map'
'parallel'
'scatterplot'
'stacked-area'
'stacked-bar'

data

Object[]

Array of plain objects that form the dataset. Each object is one data point (row). All field names referenced by x, y, color, size, label, and split must appear as properties on these objects.

string | string[]

Field name(s) for the horizontal axis. Passing a single string maps that field to the x-axis. Passing an array of two strings creates a faceted (small-multiples) layout along the x dimension: the first string is the outer facet dimension, the second is the inner axis field.

string | string[]

Field name(s) for the vertical axis. Follows the same single-field or faceted-array semantics as x.

color

string

Field name used for color encoding. Taucharts automatically assigns colors from the default brewer. Override the color mapping with guide.color.brewer.

size

string

Field name used for size encoding. Applicable to scatterplot and other element types that support variable point size.

label

string

Field name whose value is displayed as a text label on each chart element.

split

string

Field name used to split a single line or area series into multiple independent series. Each unique value in this field produces a separate visual trace.

string

Optional unique identifier for the chart instance. Not used by the rendering engine but can be helpful for plugin authors or test selectors.

guide

ChartGuide | ChartGuide[]

Visual configuration for axes, padding, colors, grid lines, and interpolation. Pass a single object for flat charts, or an array of objects for faceted layouts where each element configures one facet level. See ChartGuide below.

settings

ChartSettings

Rendering and layout settings that override the global defaults. See ChartSettings below.

dimensions

object

Explicit dimension type declarations. When omitted Taucharts auto-detects dimension types from the data. Use this field to override the inferred types.

Show dimension descriptor fields

[field].type

'category' | 'measure' | 'order'

required

Semantic type of the dimension. 'category' maps to an ordinal scale, 'measure' to a quantitative scale, and 'order' to an ordered categorical scale.

[field].scale

'ordinal' | 'period' | 'time' | 'linear' | 'logarithmic'

Scale type override. When omitted Taucharts picks the most appropriate scale for the declared dimension type.

[field].order

string[]

Explicit sort order for 'order' type dimensions. Values not present in this array are appended at the end in the order they appear in the data.

plugins

PluginObject[]

Array of plugin instances to enable. Each plugin is a PluginObject — a plain object with optional init, destroy, and onRender lifecycle hooks. Obtain built-in plugins via Taucharts.api.plugins.get(name).

Show PluginObject interface

init

(chart: Plot) => void

Called once when the plugin is attached to the chart during construction. Receives the chart instance.

destroy

() => void

Called when the chart is destroyed or the config is updated. Use to clean up DOM nodes or event listeners.

onRender

() => void

Called after each render cycle completes.

ChartGuide

ChartGuide controls the visual appearance of axes, padding, grid lines, and element drawing. All fields are optional.

guide.x

object

Configuration for the x-axis.

Show x-axis fields

nice

boolean

Round the domain endpoints to “nice” round values. Defaults to true.

min

number

Hard minimum for the axis domain, overriding the data-driven minimum.

max

number

Hard maximum for the axis domain, overriding the data-driven maximum.

label

string | { text: string; padding: number }

Axis label text. Pass a string for the default padding, or an object to control the distance between the axis and the label text.

tickPeriod

string

Named tick period for time-based axes (e.g. 'year', 'quarter', 'month', 'week', 'day'). Custom periods can be registered via Taucharts.api.tickPeriod.add.

tickFormat

string | ((x: any) => string)

Tick label formatter. Pass a named format string registered in Taucharts.api.tickFormat, or a custom function that receives the tick value and returns a string.

guide.y

object

Configuration for the y-axis. Accepts the same fields as guide.x.

Show y-axis fields

nice

boolean

Round the domain endpoints to “nice” round values.

min

number

Hard minimum for the axis domain.

max

number

Hard maximum for the axis domain.

label

string | { text: string; padding: number }

Axis label text or object with explicit padding.

tickPeriod

string

Named tick period for time-based axes.

tickFormat

string | ((x: any) => string)

Tick label formatter string or function.

guide.padding

object

Inner padding around the chart canvas in pixels.

Show padding fields

number

required

Top padding in pixels.

number

required

Right padding in pixels.

number

required

Bottom padding in pixels.

number

required

Left padding in pixels.

guide.color

object

Color channel configuration.

Show color fields

brewer

string[] | { [group: string]: string }

Custom color palette. Pass an array of hex/CSS color strings for sequential assignment, or an object mapping category values to specific colors.

guide.showAnchors

'always' | 'hover' | 'never'

Controls when anchor dots are shown on line and area charts. 'always' shows them permanently, 'hover' shows them only on pointer interaction, 'never' hides them.

guide.interpolate

Curve interpolation method for line and area charts. Defaults to 'linear'.

'linear' — straight segments between points
'smooth' — cubic bezier curve, may overshoot data values
'smooth-keep-extremum' — cubic bezier that preserves local extrema
'step' — horizontal then vertical step
'step-before' — vertical then horizontal step
'step-after' — horizontal then vertical step (step occurs after the point)

guide.split

boolean

When true, splits the series by the split field even when no color field is set.

guide.showGridLines

'x' | 'y' | 'xy'

Which grid lines to render. 'x' draws vertical grid lines at each x tick, 'y' draws horizontal lines at each y tick, 'xy' draws both.

ChartSettings

ChartSettings controls rendering behaviour and axis layout. All fields are optional; unset fields fall back to the values in Taucharts.api.globalSettings.

settings.animationSpeed

number

default:"750"

Duration of entry/exit animations in milliseconds. Set to 0 to disable animations.

settings.renderingTimeout

number

default:"10000"

Maximum time in milliseconds allowed for a single render pass before the timeout warning is shown. Set to Infinity to disable the timeout.

settings.asyncRendering

boolean

default:"true"

When true the rendering pipeline yields to the browser event loop between chunks, preventing UI freezes on large datasets.

settings.syncRenderingInterval

number

default:"50"

When asyncRendering is true, the number of milliseconds between yielding control back to the browser.

settings.syncPointerEvents

boolean

default:"false"

When true, pointer event handlers run synchronously instead of being deferred with requestAnimationFrame.

settings.handleRenderingErrors

boolean

default:"false"

When true, rendering errors are caught and surfaced as a 'renderingerror' event instead of propagating as uncaught exceptions.

settings.defaultColorBrewer

string[]

Default color palette used for measure-type color dimensions. Overrides the built-in viridis-derived palette.

settings.defaultClassBrewer

string[]

Default CSS class sequence used for category-type color dimensions (color20-1 through color20-20 by default).

settings.log

(msg: string, type: 'ERROR' | 'WARNING' | 'INFO' | 'LOG') => void

Custom logging function. Receives a message string and a severity level. Defaults to console[type.toLowerCase()].

settings.facetLabelDelimiter

string

default:"' → '"

String inserted between outer and inner facet label values in faceted chart titles.

settings.excludeNull

boolean

default:"true"

When true, data rows that have null or undefined values in any dimension field are silently excluded before rendering.

settings.fitModel

default:"'normal'"

Controls how the chart fills its container when there is excess or insufficient space.

settings.layoutEngine

'NONE' | 'EXTRACT'

default:"'EXTRACT'"

Layout algorithm. 'EXTRACT' pulls axes out of the plot area into dedicated rows/columns. 'NONE' leaves axes embedded inside the plot.

settings.autoRatio

boolean

default:"true"

When true, automatically adjusts the plot aspect ratio to fit the container.

settings.specEngine

Array<{ name?: 'COMPACT' | 'AUTO'; width?: number; height?: number }>

Ordered list of spec engine breakpoints. Each entry defines the maximum container size at which a named engine is active. Defaults to COMPACT below 600×400 px and AUTO above.

settings.utcTime

boolean

default:"false"

When true, all time-based scales and tick periods use UTC instead of local time.

settings.defaultFormats

{ [name: string]: string }

Named default format strings applied to dimensions when no explicit tickFormat is set. Keys are dimension type strings such as 'measure' or 'measure:time'.

settings.minChartWidth

number

default:"300"

Minimum chart width in pixels. The chart will not render below this width.

settings.minChartHeight

number

default:"200"

Minimum chart height in pixels.

settings.minFacetWidth

number

default:"150"

Minimum width of an individual facet panel in pixels.

settings.minFacetHeight

number

default:"100"

Minimum height of an individual facet panel in pixels.

settings.xAxisTickLabelLimit

number

default:"150"

Maximum width in pixels of an x-axis tick label before it is truncated or wrapped.

settings.yAxisTickLabelLimit

number

default:"150"

Maximum width in pixels of a y-axis tick label before truncation or wrapping.

Full example

import Taucharts from 'taucharts';

const data = [
  { date: new Date('2024-01-01'), sales: 420, category: 'Electronics', region: 'North' },
  { date: new Date('2024-02-01'), sales: 380, category: 'Electronics', region: 'North' },
  { date: new Date('2024-01-01'), sales: 510, category: 'Clothing',    region: 'South' },
  { date: new Date('2024-02-01'), sales: 490, category: 'Clothing',    region: 'South' },
  { date: new Date('2024-03-01'), sales: 560, category: 'Electronics', region: 'North' },
  { date: new Date('2024-03-01'), sales: 430, category: 'Clothing',    region: 'South' },
];

const chart = new Taucharts.Chart({
  type: 'line',

  // Field-to-channel mappings
  x: 'date',
  y: 'sales',
  color: 'category',

  data,

  // Explicit dimension type declarations
  dimensions: {
    date:     { type: 'measure', scale: 'time' },
    sales:    { type: 'measure', scale: 'linear' },
    category: { type: 'category' },
    region:   { type: 'category' },
  },

  // Visual guide configuration
  guide: {
    x: {
      label: 'Month',
      tickPeriod: 'month',
      tickFormat: 'month',
    },
    y: {
      label: { text: 'Sales (units)', padding: 12 },
      min: 0,
      nice: true,
    },
    color: {
      brewer: {
        Electronics: '#4e79a7',
        Clothing:    '#f28e2b',
      },
    },
    showGridLines: 'y',
    interpolate: 'smooth',
    showAnchors: 'hover',
    padding: { t: 10, r: 20, b: 40, l: 60 },
  },

  // Rendering settings
  settings: {
    animationSpeed: 400,
    asyncRendering: true,
    excludeNull: true,
    fitModel: 'normal',
    utcTime: false,
  },

  // Plugins
  plugins: [
    Taucharts.api.plugins.get('tooltip')({
      fields: ['date', 'sales', 'category'],
      formatters: {
        sales: { label: 'Sales', format: (v) => v.toLocaleString() },
      },
    }),
    Taucharts.api.plugins.get('legend')(),
  ],
});

chart.renderTo('#chart-container');

When dimensions is omitted Taucharts infers types automatically from the data: JavaScript Date objects become measure / time, numbers become measure / linear, and strings become category / ordinal. Explicit declarations are only needed when the inference produces unexpected results or when you want an 'order' type with a custom sort.

Core API

Utilities

ChartSpec configuration reference

Top-level fields

ChartGuide

ChartSettings

Full example

Build docs developers (and LLMs) love

Core API

Utilities

Documentation Index

​Top-level fields

​ChartGuide

​ChartSettings

​Full example

Build docs developers (and LLMs) love

Top-level fields

ChartGuide

ChartSettings

Full example