vue-charts
GitHub
Components

Composables

Read chart size, axis scales and tooltip state from your own components

The composables give your own components read access to a chart: its size, its plot area, its axes and its tooltip state. Use them to draw overlays, such as target bands, annotations or a custom readout, without the deprecated <Customized> wrapper.

Draw an overlay

Call the composables in a component that you place inside the chart. Children of a chart render inside its SVG surface, so the component returns SVG elements.

TargetBand.vue
<script setup lang="ts">
import { computed } from 'vue'
import { usePlotArea, useYAxisScale } from 'vccs'

const props = defineProps<{ from: number, to: number }>()
const plot = usePlotArea()
const y = useYAxisScale()
const top = computed(() => y.value?.(props.to))
const bottom = computed(() => y.value?.(props.from))
</script>

<template>
  <rect
    v-if="top != null && bottom != null"
    :x="plot.x"
    :y="top"
    :width="plot.width"
    :height="bottom - top"
    fill="#14b8a6"
    opacity="0.12"
  />
</template>

<LineChart :data="data" :height="300">
  <YAxis />
  <TargetBand :from="250" :to="320" />
  <Line data-key="visits" />
</LineChart>

Where they work

  • Call them in setup of a component that renders inside a chart. Outside a chart they throw an error.
  • The axis composables need a cartesian chart (LineChart, BarChart, AreaChart, ScatterChart, ComposedChart). In a polar chart they return an empty domain and no useful scale.
  • Standalone charts (Treemap, Sankey, SunburstChart, Heatmap, CalendarHeatmap, CohortChart, Tracker, Sparkline, JourneySankey) have no axes: the axis composables throw there. usePlotArea, useChartWidth and useChartHeight report a width and height of 0 in these charts. Only the tooltip composables give useful values. BarList is an HTML list, not a chart surface: all composables throw inside it.
  • Every composable returns a Vue ComputedRef. Read it with .value in script, or without .value in a template.

Layout

ComposableReturnsDescription
usePlotArea()ComputedRef<{ x, y, width, height }>The area inside the margins, axes, legend and brush, where the series draw. In px from the top left of the chart
useChartWidth()ComputedRef<number>Chart width in px
useChartHeight()ComputedRef<number>Chart height in px
useMargin()ComputedRef<{ top, right, bottom, left }>The chart margin prop, with defaults

Axes

The types ScaleFunction, InverseScaleFunction and CartesianDataPoint are exported from vccs. Each axis composable takes an optional axis id (x-axis-id or y-axis-id on the axis). The default is 0, the id of an axis without one.

ComposableReturnsDescription
useXAxisDomain(id?) / useYAxisDomain(id?)ComputedRef<[number, number] | (number | string | Date)[] | undefined>The final domain: [min, max] for a number axis, the categories for a category axis
useXAxisTicks(id?) / useYAxisTicks(id?)ComputedRef<{ value, coordinate, index?, offset? }[] | undefined>The ticks the axis draws, with their pixel coordinate
useXAxisScale(id?) / useYAxisScale(id?)ComputedRef<((value: unknown) => number | undefined) | undefined>Maps a data value to a pixel position. The function returns undefined for a value outside a category axis
useXAxisInverseScale(id?) / useYAxisInverseScale(id?)ComputedRef<((px: number) => unknown) | undefined>Maps a pixel position back to a data value
useXAxisInverseDataSnapScale(id?) / useYAxisInverseDataSnapScale(id?)ComputedRef<((px: number) => unknown) | undefined>Like the inverse scale, but returns the nearest value in the data
useXAxisInverseTickSnapScale(id?) / useYAxisInverseTickSnapScale(id?)ComputedRef<((px: number) => unknown) | undefined>Like the inverse scale, but returns the value of the nearest tick
useCartesianScale(point, xId?, yId?)ComputedRef<{ x, y } | undefined>Maps a data point { x, y } to pixels with both scales. undefined when a scale or a value is missing

The results are undefined until the axis exists and has data. Always guard them, as the example above does with y.value?.(…).

Tooltip

ComposableReturnsDescription
useIsTooltipActive()ComputedRef<boolean>true while a tooltip shows, from pointer or keyboard
useActiveTooltipLabel()ComputedRef<string | undefined>The label of the active item, for example the category on the X axis
useActiveTooltipCoordinate()ComputedRef<{ x, y } | undefined>The pixel position of the active item
useActiveTooltipDataPoints()ComputedRef<unknown[]>The data rows of the active item, one per row, without duplicates. Empty when no tooltip shows

The tooltip composables also work in standalone charts. They follow the same selection as <Tooltip> and v-model:active-index; see Events and v-model.

Related

Shapes

SVG building blocks for custom bars, points, sectors and cursors

Custom overlays

Draw your own SVG inside a chart with the default slot and the chart composables

Copyright © 2026