Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TargetProcess/tauCharts/llms.txt

Use this file to discover all available pages before exploring further.

Scales are the bridge between raw data values and the pixel positions, colors, or sizes you see in a chart. Taucharts registers ten scale types internally and selects the right one automatically based on your data, but you can override the choice using the dimensions property and fine-tune behaviour through the guide.

​
Registered scale types

ScaleKeyUse case
identityidentityInternal use; maps values directly to themselves
colorcolorMaps dimension values to colors from the color brewer
fillfillChoropleth fill colors on map charts
sizesizeMaps numeric values to point radius
ordinalordinalDiscrete categories with equal spacing
periodperiodTime axis snapped to calendar periods (day, week, month, …)
timetimeContinuous time axis using d3 time scales
linearlinearContinuous numeric axis
logarithmiclogarithmicContinuous numeric axis with logarithmic spacing
valuevalueInternal use for pass-through values
The scales you set via dimensions[field].scale are ordinal, period, time, linear, and logarithmic.

​
Setting a scale

Override the auto-detected scale for any field in the dimensions map: 
const chart = new Taucharts.Chart({
  type: 'line',
  x: 'date',
  y: 'downloads',
  data: [...],
  dimensions: {
    date: { type: 'measure', scale: 'time' },
    downloads: { type: 'measure', scale: 'logarithmic' },
  },
});

​
Ordinal scale

The ordinal scale maps discrete string values to evenly spaced positions. It is the default for category and order dimension types. 
dimensions: {
  status: { type: 'category', scale: 'ordinal' },
}
To control the order that values appear on the axis, combine the ordinal scale with the order array on an order-type dimension: 
dimensions: {
  priority: {
    type: 'order',
    scale: 'ordinal',
    order: ['Low', 'Medium', 'High', 'Critical'],
  },
}
Values not included in the order array are appended at the end in their original insertion order.

​
Linear scale

The linear scale is the default for finite numeric fields. Configure the axis domain bounds and rounding via the guide: 
const chart = new Taucharts.Chart({
  type: 'bar',
  x: 'category',
  y: 'value',
  data: [...],
  guide: {
    y: {
      min: 0,
      max: 100,
      nice: true,   // extends domain to round tick values
    },
  },
});
The scale clamps values to the domain, so data points outside [min, max] are drawn at the boundary rather than overflowing.

​
Time scale

The time scale maps JavaScript Date objects (or ISO strings coerced to dates) to a continuous axis. Taucharts uses d3’s scaleTime locally and scaleUtc when utcTime is enabled. 
dimensions: {
  createdAt: { type: 'measure', scale: 'time' },
}

​
UTC mode

Set utcTime: true in settings to interpret all time values as UTC instead of local time. This affects axis tick alignment, tick format output, and period boundaries. 
settings: {
  utcTime: true,
}

​
Tick periods

Combine the time scale with tickPeriod in the guide to snap ticks and labels to calendar boundaries: 
guide: {
  x: {
    tickPeriod: 'month',
    tickFormat: 'month-short',
  },
}
Built-in period names: day, week, month, quarter, year.

​
Period scale

The period scale is a discrete variant of the time scale. It snaps values to the start of the nearest period boundary, making each period a uniform-width band rather than a proportional interval. 
dimensions: {
  sprint: { type: 'measure', scale: 'period' },
}
Rows where a period-scale field is null are excluded from rendering by default, the same as measure fields. See excludeNull in Chart settings.

​
Logarithmic scale

Use the logarithmic scale for numeric data that spans several orders of magnitude: 
dimensions: {
  pageViews: { type: 'measure', scale: 'logarithmic' },
}
The min and max guide options work the same as with the linear scale. Avoid zero or negative values in the domain—they cannot be represented on a log scale.

​
Custom tick periods

Register a new named period with Taucharts.api.tickPeriod.add(). A period definition requires two functions: cast snaps a date to the start of its period, and next advances a date by one period. 
Taucharts.api.tickPeriod.add('fortnight', {
  cast: (d) => {
    // snap to the start of the nearest two-week block
    const ms = d.getTime();
    const twoWeeks = 1000 * 60 * 60 * 24 * 14;
    return new Date(Math.floor(ms / twoWeeks) * twoWeeks);
  },
  next: (d) => {
    return new Date(d.getTime() + 1000 * 60 * 60 * 24 * 14);
  },
});

// Use it like any built-in period
guide: {
  x: { tickPeriod: 'fortnight', tickFormat: 'day' },
}
You can also retrieve a registered period programmatically: 
const monthPeriod = Taucharts.api.tickPeriod.get('month', { utc: true });
const startOfMonth = monthPeriod.cast(new Date());
const nextMonth = monthPeriod.next(startOfMonth);

​
Custom tick formats

Register a named formatter with Taucharts.api.tickFormat.add(). The function receives the raw tick value and must return a string. 
Taucharts.api.tickFormat.add('sprint-label', (value) => {
  const week = Math.ceil((value.getDate()) / 7);
  return `W${week} ${value.toLocaleString('default', { month: 'short' })}`;
});

// Reference by name in the guide
guide: {
  x: { tickFormat: 'sprint-label' },
}
Retrieve a registered formatter: 
const fmt = Taucharts.api.tickFormat.get('month');
console.log(fmt(new Date('2024-03-15'))); // "March"
Custom tick periods and formats are global. Register them once before creating any charts that use them.

Build docs developers (and LLMs) love

Get started for freeTalk to us