Time Cartesian Axis

The time scale is used to display times and dates. When building its ticks, it will automatically calculate the most comfortable unit base on the size of the scale.

Data Sets

Input Data

The x-axis data points may additionally be specified via the t or x attribute when using the time scale.

  1. data: [{
  2. x: new Date(),
  3. y: 1
  4. }, {
  5. t: new Date(),
  6. y: 10
  7. }]

Date Formats

When providing data for the time scale, Chart.js supports all of the formats that Moment.js accepts. See Moment.js docs for details.

Configuration Options

The following options are provided by the time scale. You may also set options provided by the common tick configuration.

NameTypeDefaultDescription
adapters.dateobject{}Options for adapter for external date library if that adapter needs or supports options
distributionstring'linear'How data is plotted. more…
boundsstring'data'Determines the scale bounds. more…
ticks.sourcestring'auto'How ticks are generated. more…
time.displayFormatsobjectSets how different time units are displayed. more…
time.isoWeekdaybooleanfalseIf true and the unit is set to 'week', then the first day of the week will be Monday. Otherwise, it will be Sunday.
time.maxTimeIf defined, this will override the data maximum.
time.minTimeIf defined, this will override the data minimum.
time.parserstring|functionCustom parser for dates. more…
time.roundstringfalseIf defined, dates will be rounded to the start of this unit. See Time Units below for the allowed units.
time.tooltipFormatstringThe Moment.js format string to use for the tooltip.
time.unitstringfalseIf defined, will force the unit to be a certain type. See Time Units section below for details.
time.stepSizenumber1The number of units between grid lines.
time.minUnitstring'millisecond'The minimum display format to be used for a time unit.

Time Units

The following time measurements are supported. The names can be passed as strings to the time.unit config option to force a certain unit.

  • 'millisecond'
  • 'second'
  • 'minute'
  • 'hour'
  • 'day'
  • 'week'
  • 'month'
  • 'quarter'
  • 'year'
    For example, to create a chart with a time scale that always displayed units per month, the following config could be used.
  1. var chart = new Chart(ctx, {
  2. type: 'line',
  3. data: data,
  4. options: {
  5. scales: {
  6. xAxes: [{
  7. type: 'time',
  8. time: {
  9. unit: 'month'
  10. }
  11. }]
  12. }
  13. }
  14. });

Display Formats

The following display formats are used to configure how different time units are formed into strings for the axis tick marks. See Moment.js for the allowable format strings.

NameDefaultExample
millisecond'h:mm:ss.SSS a''11:20:01.123 AM'
second'h:mm:ss a''11:20:01 AM'
minute'h:mm a''11:20 AM'
hour'hA''11AM'
day'MMM D''Sep 4'
week'll''Sep 4 2015'
month'MMM YYYY''Sep 2015'
quarter'[Q]Q - YYYY''Q3 - 2015'
year'YYYY''2015'

For example, to set the display format for the quarter unit to show the month and year, the following config would be passed to the chart constructor.

  1. var chart = new Chart(ctx, {
  2. type: 'line',
  3. data: data,
  4. options: {
  5. scales: {
  6. xAxes: [{
  7. type: 'time',
  8. time: {
  9. displayFormats: {
  10. quarter: 'MMM YYYY'
  11. }
  12. }
  13. }]
  14. }
  15. }
  16. });

Scale Distribution

The distribution property controls the data distribution along the scale:

  • 'linear': data are spread according to their time (distances can vary)
  • 'series': data are spread at the same distance from each other
  1. var chart = new Chart(ctx, {
  2. type: 'line',
  3. data: data,
  4. options: {
  5. scales: {
  6. xAxes: [{
  7. type: 'time',
  8. distribution: 'series'
  9. }]
  10. }
  11. }
  12. });

Scale Bounds

The bounds property controls the scale boundary strategy (bypassed by min/max time options).

  • 'data': makes sure data are fully visible, labels outside are removed
  • 'ticks': makes sure ticks are fully visible, data outside are truncated

Ticks Source

The ticks.source property controls the ticks generation.

  • 'auto': generates "optimal" ticks based on scale size and time options
  • 'data': generates ticks from data (including labels from data {t|x|y} objects)
  • 'labels': generates ticks from user given data.labels values ONLY

Parser

If this property is defined as a string, it is interpreted as a custom format to be used by Moment.js to parse the date.

If this is a function, it must return a Moment.js object given the appropriate data value.