React ChartsTime Axis

Time axes are used to display time-based data in a chart. They can be used to show data at different levels of granularity, such as years, months, days, or even hours and minutes.

Time can be provided as number or Date objects, where number values are interpreted as timestamps derived from Unix time.

There are three methods of displaying time along an axis.

• Unit Time Axis - Each 'unit' has a dedicated band within the domain.
• Ordinal Time Axis - Only provided values are shown, with missing values omitted.
• Continuous Time Axis - Data is shown on a continuous scale.

The difference between a Unit Time Axis, an Ordinal Time Axis, and a Continuous Time Axis is demonstrated in the following example:

Unit Time Copy Link

The Unit Time Axis will plot time values with evenly spaced bands for each unit of time in the domain, regardless of the actual time span between them or missing data.

For example, with a month unit, dates of 01 Jan and 30 Mar will appear as three evenly spaced items representing "January", "February" and "March".

{
    type: 'unit-time',
    position: 'bottom',
}

Custom Unit Copy Link

The Unit Time Axis assumes that data is provided with one item per unit, and will infer a unit based on the data.

For some scenarios - such as datasets with missing data points - it may be necessary to specify the unit explicitly. To explicitly set the unit, provide an AgTimeInterval string or AgTimeIntervalUnit object.

{
    type: 'unit-time',
    position: 'bottom',
    unit:  'day', // every day
}

In this configuration:

• unit must be one of millisecond, second, minute, hour, day, week, month, or year.

Weekly Data Example Copy Link

The AgTimeIntervalUnit object supports advanced configuration for more complex unit requirements such as weekly data.

{
    type: 'unit-time',
    position: 'bottom',
    unit: {
        unit: 'day',
        step: 7, //every 7 days (weekly)
        epoch: new Date(2024, 0, 1), //start the week on Monday
    },
}

In this example:

• step specifies the multiple of the unit to use. In this example, step: 7 combined with unit: 'day' will display one data point for any provided date within each week.
• epoch is an optional Date that specifies the starting point for the unit. In this example, the week runs from Monday to Monday.
• In this example, a Formatter is used to format the labels as numbered weeks of the year.

For a full list of configuration options see Unit Time Axis Options.

Ordinal Time Copy Link

Data points plotted along an Ordinal Time Axis will be arranged according to their position in time, ignoring the time intervals between them. This is unlike the Unit Time and Continuous Time Axis, which represent time with consistent intervals.

For example, if the Ordinal Time Axis is used to plot daily values but there are no data points for the weekend, values for Friday and Monday will be equally spaced, without gaps for Saturday and Sunday.

Ordinal Time axes are commonly used for financial data on the x-axis, usually placed at the bottom of a chart.

A basic Ordinal Time Axis configuration looks like this:

{
    type: 'ordinal-time',
    position: 'bottom',
}

For a full list of configuration options see Ordinal Time Axis Options.

Continuous Time Copy Link

The time axis is similar to the number axis in the sense that it is also used to plot continuous values.

Time axes are typically used as x-axes and placed at the bottom of a chart. The simplest time axis config looks like this:

{
    type: 'time',
    position: 'bottom',
}

For a full list of configuration options see Continuous Time Axis Options.

Time Intervals Copy Link

The Axis Interval of Time Axes labels, grid lines and ticks can be customised with the interval.step parameter, which should be a AgTimeInterval or AgTimeIntervalUnit.

{
    interval: {
        step: 'month',
    },
}

{
    interval: {
            step: {
                unit: 'day',
                step: 7,  // every 7 days (weekly)
                new Date('2024-01-01') //start the week on a Monday
            },
    },
}

In this configuration:

• unit must be one of millisecond, second, minute, hour, day, week, month, or year.
• step is an optional number that specifies the multiple of the unit to use.
• epoch is an optional Date that specifies the starting point for the interval.

See Time Interval for more information on the interval.step property.

Parent Levels Copy Link

The parentLevel option allows displaying labels and ticks for the parent level of the time axes. For example, if the axis is showing monthly data, the parent level would be the years. These levels are based on the data displayed, and adjust dynamically as the user zooms in and out.

It is enabled by default for the Unit Time Axis, and can be opted into for the Continuous Time Axis and Ordinal Time Axis.

{
    parentLevel: {
        enabled: true,
    },
}

In this example:

• The data is shown with a 'day' unit, and the parent level of 'month' is shown in bold.
• As you zoom out, the labels will change to 'month', with a parent level of 'year'.

Customisation Copy Link

Parent level labels and ticks options are inherited from the axes label and tick options, but can be customised with the parentLevel options.

{
    tick: {
        width: 0,
    },
    label: {
        format: {
            day: '%e',
            month: '%b',
        },
    },
    parentLevel: {
        enabled: true,
        tick: {
            width: 1,
        },
        label: {
            format: {
                month: '%e\n%b',
                year: '%b\n%Y',
            },
        },
    },
}

In this configuration:

• The label format is set to show the day and month for the day level, and the month for the month level.
• The parent level tick is given a width of 1 to show the parent level ticks.
• The parent level label format is set to show the day and month on separate lines for the month level, and the month and year on separate lines for the year level.

See Axis Labels and the Formatters pages for more information on formatting labels.

API Reference Copy Link