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.

Tick periods control how time-based axes are segmented and labeled. When a field is mapped to a period scale, Taucharts uses a period definition — a pair of cast and next functions — to align date values to boundaries and step through them. The tickPeriod API lets you retrieve built-in periods or register custom ones.

​
API reference

​
Taucharts.api.tickPeriod.get
function
Retrieve a period object by name.
tickPeriod.get(
  name: string,
  settings?: { utc?: boolean }
): { cast: (d: Date) => Date; next: (d: Date) => Date; }
Returns null if the name is not registered. Pass { utc: true } to retrieve the UTC variant of a period.
​
Taucharts.api.tickPeriod.add
function
Register a new named period.
tickPeriod.add(
  name: string,
  period: { cast: (d: Date) => Date; next: (d: Date) => Date; },
  settings?: { utc?: boolean }
): void
Call with { utc: true } to register the UTC variant separately from the local-time variant.

​
Period object shape

A period consists of two pure functions that operate on Date objects:
​
cast
(d: Date) => Date
required
Round a date down to the start of the period boundary. For example, a month cast rounds any date to the first of its month at midnight.
​
next
(d: Date) => Date
required
Advance a date to the start of the next period boundary. Must always move forward in time.

​
Built-in periods

The following periods are available in both local-time and UTC variants (suffix -utc not needed; pass { utc: true } to get/add):
NameBoundaryStep
dayMidnight of each day+1 day
weekMidnight of Sunday of each week+7 days
monthFirst day of each month at midnight+1 month
quarterFirst day of each calendar quarter at midnight+3 months
yearJanuary 1 at midnight+1 year

​
Using a period in guide

Set tickPeriod on the x or y axis guide. The field must use a period scale (set automatically for time dimensions, or explicitly via dimensions): 
new Taucharts.Chart({
  type: 'line',
  x: 'date',
  y: 'value',
  data: [...],
  dimensions: {
    date: { type: 'measure', scale: 'period' }
  },
  guide: {
    x: { tickPeriod: 'month' }
  }
});

​
UTC time support

By default all periods use local time. Enable UTC globally with the utcTime setting, or pass { utc: true } when retrieving a period directly: 
// Global UTC mode — affects all period and time scales
Taucharts.api.globalSettings.utcTime = true;

// Retrieve a UTC period directly
const utcMonth = Taucharts.api.tickPeriod.get('month', { utc: true });
When utcTime: true is set in ChartSettings, Taucharts automatically selects UTC variants for all period and time scales in that chart.

​
Creating a custom period

Register a custom period before creating charts that reference it. Both the local-time and UTC variants should be registered if you need UTC support: 
// Local-time fortnight (2-week) period
Taucharts.api.tickPeriod.add('fortnight', {
  cast: (d) => {
    // Round down to the nearest Monday, then to the nearest even week
    const date = new Date(d);
    date.setHours(0, 0, 0, 0);
    // Align to week boundary (Sunday = 0)
    date.setDate(date.getDate() - date.getDay());
    // Snap to even 2-week blocks from epoch
    const weeksSinceEpoch = Math.floor(date.getTime() / (7 * 24 * 3600 * 1000));
    if (weeksSinceEpoch % 2 !== 0) {
      date.setDate(date.getDate() - 7);
    }
    return date;
  },
  next: (d) => {
    const date = new Date(d);
    date.setDate(date.getDate() + 14);
    return date;
  }
});

// UTC variant
Taucharts.api.tickPeriod.add('fortnight', {
  cast: (d) => {
    const date = new Date(d);
    date.setUTCHours(0, 0, 0, 0);
    date.setUTCDate(date.getUTCDate() - date.getUTCDay());
    const weeksSinceEpoch = Math.floor(date.getTime() / (7 * 24 * 3600 * 1000));
    if (weeksSinceEpoch % 2 !== 0) {
      date.setUTCDate(date.getUTCDate() - 7);
    }
    return date;
  },
  next: (d) => {
    const date = new Date(d);
    date.setUTCDate(date.getUTCDate() + 14);
    return date;
  }
}, { utc: true });

// Use the custom period
new Taucharts.Chart({
  type: 'bar',
  x: 'date',
  y: 'commits',
  data: [...],
  dimensions: { date: { type: 'measure', scale: 'period' } },
  guide: {
    x: { tickPeriod: 'fortnight' }
  }
});
Period names are lowercased internally. 'Fortnight' and 'fortnight' resolve to the same entry.

Build docs developers (and LLMs) love

Get started for freeTalk to us