Coordinate Systems

vccs uses different coordinate systems for different purposes. Understanding them helps when placing annotations, custom elements, or interpreting event data.

Data values

Axes, reference elements and series take data values: the values in your rows. When you set :domain="[0, 100]" on a YAxis, the axis covers the data values 0 to 100. Every reference element takes data values too:

<!-- A horizontal line at the data value 75 -->
<ReferenceLine :y="75" stroke="#ef4444" stroke-dasharray="3 3" />

<!-- A vertical line at a category -->
<ReferenceLine x="March" stroke="#14b8a6" />

<!-- A band from one category to another -->
<ReferenceArea x1="Feb" x2="Apr" fill="#f97316" :fill-opacity="0.1" />

<!-- A dot at one data point -->
<ReferenceDot x="Mar" :y="600" :r="6" />

Data values to pixels

The chart converts data values to pixels inside the SVG. The origin (0, 0) is the top-left corner of the SVG; the plot area starts after the margin and the axes. To draw your own SVG at a data value, read the scales in a component placed in the chart's default slot:

<script setup lang="ts">
import { useCartesianScale, usePlotArea } from 'vccs'

const point = useCartesianScale({ x: 'Mar', y: 600 })
const plot = usePlotArea()
</script>

<template>
  <line
    v-if="point"
    :x1="point.x"
    :x2="point.x"
    :y1="plot.y"
    :y2="plot.y + plot.height"
    stroke="#14b8a6"
  />
</template>

useXAxisScale() and useYAxisScale() return the scale functions, and the inverse scales map a pixel back to a data value. Custom overlays lists every composable.

Cartesian vs Polar

Cartesian charts (BarChart, LineChart, AreaChart, ScatterChart, ComposedChart) use X/Y axes with rectangular coordinate grids.

Polar charts (PieChart, RadarChart, RadialBarChart) use angle/radius with circular coordinate systems:

• <PolarAngleAxis> — maps data to angles around the circle
• <PolarRadiusAxis> — maps data to distance from center
• <PolarGrid> — renders circular or polygon grid lines

<RadarChart :data="data" cx="50%" cy="50%">
  <PolarGrid />
  <PolarAngleAxis data-key="subject" />
  <PolarRadiusAxis />
  <Radar data-key="score" stroke="#f97316" fill="#f97316" :fill-opacity="0.5" />
</RadarChart>

See Polar Axes and Grid for all props of these three components.

Annotations with ReferenceArea and ReferenceLine

Reference elements annotate a chart in data values:

Convert between coordinates in code

The composables give your components the axis scales of the chart. useXAxisScale() and useYAxisScale() map data values to pixels, the inverse scales map pixels back to data values, and usePlotArea() gives the pixel rectangle where the series draw.