---

name: chartjs-axes description: This skill should be used when the user asks "Chart.js axes", "Chart.js scales", "Chart.js x-axis", "Chart.js y-axis", "Chart.js time axis", "Chart.js logarithmic scale", "Chart.js axis labels", "Chart.js ticks", "Chart.js grid lines", "Chart.js multiple axes", "Chart.js dual axis", "Chart.js axis title", "Chart.js axis range", "Chart.js min max", "stacked axes", "Chart.js radial axis", or needs help configuring Chart.js v4.5.1 axes and scales.

Chart.js Axes Configuration (v4.5.1)

Comprehensive guide to configuring axes, scales, ticks, and grid lines in Chart.js.

Axis Types

Cartesian Axes (x/y)

Type	Use Case	Import
category	String labels	CategoryScale
linear	Numeric data	LinearScale
logarithmic	Exponential data	LogarithmicScale
time	Date/time data	TimeScale
timeseries	Time series data	TimeSeriesScale

Radial Axes (r)

Type	Use Case	Import
radialLinear	Radar/polar charts	RadialLinearScale

Basic Axis Configuration

Namespace: options.scales

options: {
  scales: {
    x: {
      type: 'category',          // Scale type
      position: 'bottom',        // bottom, top, left, right
      display: true,             // Show axis
      title: {
        display: true,
        text: 'X Axis Label'
      }
    },
    y: {
      type: 'linear',
      position: 'left',
      beginAtZero: true,
      title: {
        display: true,
        text: 'Y Axis Label'
      }
    }
  }
}

Linear Scale

For numeric data:

scales: {
  y: {
    type: 'linear',
    min: 0,                      // Minimum value
    max: 100,                    // Maximum value
    suggestedMin: 0,             // Suggested min (can be exceeded by data)
    suggestedMax: 100,           // Suggested max
    beginAtZero: true,           // Force zero origin
    grace: '5%',                 // Extra space beyond min/max
    ticks: {
      stepSize: 10,              // Fixed step size
      count: 11,                 // Approximate number of ticks
      precision: 0               // Decimal places
    }
  }
}

Category Scale

For string labels:

scales: {
  x: {
    type: 'category',
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    offset: true,                // Add padding to edges
    ticks: {
      autoSkip: true,            // Skip labels if crowded
      maxRotation: 45,           // Max label rotation
      minRotation: 0             // Min label rotation
    }
  }
}

Time Scale

Requires a date adapter. Install one:

npm install chartjs-adapter-date-fns date-fns
# or
npm install chartjs-adapter-moment moment
# or
npm install chartjs-adapter-luxon luxon

import 'chartjs-adapter-date-fns';

scales: {
  x: {
    type: 'time',
    time: {
      unit: 'day',               // millisecond, second, minute, hour, day, week, month, quarter, year
      displayFormats: {
        day: 'MMM d'             // Format string
      },
      tooltipFormat: 'PP',       // Tooltip format
      parser: 'yyyy-MM-dd'       // Parse format
    },
    min: '2024-01-01',
    max: '2024-12-31',
    ticks: {
      source: 'auto'             // auto, data, labels
    }
  }
}

Time Data Formats

// ISO 8601 strings
data: ['2024-01-15', '2024-02-15', '2024-03-15']

// Date objects
data: [new Date(2024, 0, 15), new Date(2024, 1, 15)]

// Timestamps
data: [1705276800000, 1707955200000, 1710460800000]

// Object format
data: [
  { x: '2024-01-15', y: 10 },
  { x: '2024-02-15', y: 20 }
]

Logarithmic Scale

For exponential data:

scales: {
  y: {
    type: 'logarithmic',
    min: 1,                      // Must be > 0
    max: 1000000,
    ticks: {
      callback: (value) => {
        if (value === 10 || value === 100 || value === 1000) {
          return value.toLocaleString();
        }
        return '';
      }
    }
  }
}

Multiple Axes

Dual Y-Axis

data: {
  datasets: [
    {
      label: 'Revenue',
      data: [1000, 2000, 3000],
      yAxisID: 'y'               // Left axis
    },
    {
      label: 'Units',
      data: [10, 20, 30],
      yAxisID: 'y1'              // Right axis
    }
  ]
},
options: {
  scales: {
    y: {
      type: 'linear',
      position: 'left',
      title: { display: true, text: 'Revenue ($)' }
    },
    y1: {
      type: 'linear',
      position: 'right',
      title: { display: true, text: 'Units' },
      grid: {
        drawOnChartArea: false   // Hide grid for this axis
      }
    }
  }
}

Multiple X-Axes

scales: {
  x: {
    position: 'bottom',
    title: { display: true, text: 'Months' }
  },
  x2: {
    position: 'top',
    title: { display: true, text: 'Quarters' },
    grid: { drawOnChartArea: false }
  }
}

Axis Title

scales: {
  y: {
    title: {
      display: true,
      text: 'Value',
      color: '#666',
      font: {
        size: 14,
        weight: 'bold'
      },
      padding: { top: 10, bottom: 10 }
    }
  }
}

Tick Configuration

scales: {
  y: {
    ticks: {
      display: true,
      color: '#666',
      font: { size: 11 },
      padding: 5,
      align: 'center',           // start, center, end
      crossAlign: 'near',        // near, center, far
      autoSkip: true,
      autoSkipPadding: 3,
      maxTicksLimit: 11,
      includeBounds: true,

      // Custom formatting
      callback: function(value, index, ticks) {
        return '$' + value.toLocaleString();
      }
    }
  }
}

Common Tick Formats

// Currency
callback: (value) => '$' + value.toLocaleString()

// Percentage
callback: (value) => value + '%'

// Abbreviated numbers
callback: (value) => {
  if (value >= 1000000) return (value / 1000000) + 'M';
  if (value >= 1000) return (value / 1000) + 'K';
  return value;
}

// Date formatting
callback: (value) => new Date(value).toLocaleDateString()

Grid Lines

scales: {
  x: {
    grid: {
      display: true,
      color: 'rgba(0, 0, 0, 0.1)',
      lineWidth: 1,
      drawOnChartArea: true,     // Draw grid in chart area
      drawTicks: true,           // Draw tick marks
      tickLength: 8,
      tickColor: '#666',         // Tick mark color
      offset: false,
      z: -1                      // Z-index (<= 0 under datasets)
    }
  },
  y: {
    grid: {
      // Scriptable: different color for zero line
      color: (context) => {
        if (context.tick.value === 0) {
          return 'rgba(0, 0, 0, 0.5)';  // Bold zero line
        }
        return 'rgba(0, 0, 0, 0.1)';
      }
    }
  }
}

Hide Grid Lines

grid: { display: false }

Axis Border

Namespace: options.scales[scaleId].border - configures the axis border line (separate from grid lines).

scales: {
  x: {
    border: {
      display: true,             // Show axis border
      color: '#666',             // Border color
      width: 2,                  // Border width in pixels
      dash: [],                  // Solid line
      dashOffset: 0,
      z: 0                       // Z-index (> 0 on top of datasets)
    }
  },
  y: {
    border: {
      display: true,
      color: 'rgba(0, 0, 0, 0.5)',
      width: 1,
      dash: [5, 5],              // Dashed border
      dashOffset: 0
    }
  }
}

Stacked Axes

scales: {
  x: {
    stacked: true
  },
  y: {
    stacked: true
  }
}

Grouped Stacks

datasets: [
  { label: 'A1', stack: 'Stack 0', data: [1, 2, 3] },
  { label: 'A2', stack: 'Stack 0', data: [2, 3, 4] },
  { label: 'B1', stack: 'Stack 1', data: [3, 4, 5] },
  { label: 'B2', stack: 'Stack 1', data: [4, 5, 6] }
]

Radial Linear Scale

For radar and polar area charts:

scales: {
  r: {
    angleLines: {
      display: true,
      color: 'rgba(0, 0, 0, 0.1)'
    },
    grid: {
      circular: true             // Circular or straight grid
    },
    pointLabels: {
      display: true,
      font: { size: 12 }
    },
    suggestedMin: 0,
    suggestedMax: 100,
    ticks: {
      stepSize: 20,
      backdropColor: 'transparent'
    }
  }
}

Axis Range Settings

Fixed Range

scales: {
  y: {
    min: 0,
    max: 100
  }
}

Suggested Range

Data can exceed these bounds:

scales: {
  y: {
    suggestedMin: 0,
    suggestedMax: 100
  }
}

Dynamic Range with Grace

scales: {
  y: {
    grace: '5%',                 // Add 5% padding
    // or
    grace: 5                     // Add 5 units
  }
}

Axis Callbacks

scales: {
  y: {
    beforeUpdate: (axis) => { /* ... */ },
    afterUpdate: (axis) => { /* ... */ },
    beforeBuildTicks: (axis) => { /* ... */ },
    afterBuildTicks: (axis) => { /* ... */ },
    beforeDataLimits: (axis) => { /* ... */ },
    afterDataLimits: (axis) => { /* ... */ },
    beforeTickToLabelConversion: (axis) => { /* ... */ },
    afterTickToLabelConversion: (axis) => { /* ... */ },
    beforeFit: (axis) => { /* ... */ },
    afterFit: (axis) => { /* ... */ }
  }
}

Axis Defaults

Set defaults for all scales:

// Linear scale defaults
Chart.defaults.scales.linear.min = 0;

// Category scale defaults
Chart.defaults.scales.category.ticks.autoSkip = true;

// All scales
Chart.defaults.scale.grid.color = 'rgba(0, 0, 0, 0.1)';

Additional Resources

• See references/date-adapters.md for time scale adapter setup
• See references/advanced-axis-customization.md for scriptable options, tick alignment, and dynamic positioning
• See examples/dual-y-axis.html for dual axis with mixed chart types
• See examples/time-scale.html for time-based charts with date-fns adapter
• See examples/styled-axes.html for custom axis styling (borders, grids, ticks)