Skip to content

OrigamChartCartesian ​

Tightly-typed cartesian chart surface covering seven topologies: `line`, `area`, `bar`, `column`, `scatter`, `spline`, and `stepped-line`. Owns the X + Y plotting area, axes, grid, and tick labels as first-class concerns and deliberately rejects polar / radar / gauge types at the TypeScript level.

Use this component when the chart type is fixed at compile time and you want TChartCartesianKind enforced on the type prop. Use OrigamChart when you need to switch between families at runtime.

Import ​

ts
import { OrigamChartCartesian } from '@origam/ds'

Quick start ​

vue
<template>
  <origam-chart-cartesian
    type="column"
    :series="series"
    :categories="months"
    :height="320"
    :stacked="true"
    title="Monthly sales"
    subtitle="2025 vs 2026"
    @point-click="onPointClick"
  />
</template>

<script setup lang="ts">
import { OrigamChartCartesian } from '@origam/ds'
import type { IChartSeries, IChartPoint } from '@origam/ds'

const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
                 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

const series: Array<IChartSeries> = [
  { name: 'Product A', data: [10, 14, 18, 16, 22, 28, 25, 30, 33, 36, 38, 42], color: 'primary' },
  { name: 'Product B', data: [ 6, 10, 14, 12, 18, 22, 19, 24, 28, 30, 32, 35], color: 'success' }
]

function onPointClick(point: IChartPoint) {
  console.log(point.seriesName, point.x, point.y)
}
</script>

Props ​

Data ​

NameTypeDefaultDescription
seriesArray<IChartSeries>requiredOne or more data series. An empty array or every series hidden renders the #empty slot.
categoriesArray<string>[]X-axis labels. Length should match the longest series; missing entries fall back to the numeric index. Not required for scatter.

Visual ​

NameTypeDefaultDescription
typeTChartCartesianKind'line'Cartesian topology. One of 'line', 'area', 'bar', 'column', 'scatter', 'spline', 'stepped-line'.
heightnumber | string360Chart height. A plain number is px; any CSS length is accepted. Ignored when aspectRatio is set.
aspectRatiostringundefinedCSS aspect-ratio shorthand. Overrides height.
colorSchemeArray<TIntent | string>8-intent cyclePalette applied when a series omits its own color.
titlestringundefinedOptional title above the plotting area.
subtitlestringundefinedOptional subtitle below the title.

Behaviour ​

NameTypeDefaultDescription
stackedbooleanfalseStack series on top of each other. Applies to bar and column.
smoothingTChartSmoothing'none'Smoothing for line / area. 'none' = straight segments; 'curve' = Catmull-Rom Bezier. spline forces 'monotone' regardless.
animatedbooleantrueEntrance animation. Respects prefers-reduced-motion.
animationDurationnumber600Animation duration in ms.
showLegendbooleantrueToggle the legend block.
legendPositionTChartLegendPosition'bottom'Legend anchor: 'top', 'bottom', 'left', 'right'.
showTooltipbooleantrueToggle the hover tooltip.
showGridbooleantrueRender horizontal grid lines.
showAxisbooleantrueRender X / Y axes and tick labels.

Axis range and formatting ​

NameTypeDefaultDescription
yMinnumberautoOverride the auto-computed Y minimum.
yMaxnumberautoOverride the auto-computed Y maximum.
xAxisFormat(value: string | number) => stringString(value)Formatter for X-axis tick labels.
yAxisFormat(value: number) => stringString(value)Formatter for Y-axis tick labels.

Drilldown and zoom — accessible names ​

The drilldown and zoomable features each render a control whose accessible name is resolved through the DS t() mechanism (see Behaviour notes):

NameTypeDefaultDescription
drilldown.navAriaLabelstring'origam.chart.drilldown.aria_label'Locale key for the breadcrumb <nav> landmark shown while drilled in. Shared with <OrigamChartPolar>.
zoomResetLabelstring'origam.chart.zoom.reset_aria_label'Locale key for the "Reset zoom" control shown when zoomable is active and the plot is currently zoomed. Drives both its aria-label and its visible text (#764).

The rangeSelector toolbar rendered above the plot is the standalone <OrigamChartRangeSelector> component internally; its own ariaLabel prop (default 'origam.chart.range_selector.aria_label') is not yet forwarded through rangeSelector config here — pass it directly when using <OrigamChartRangeSelector> on its own.

Emits ​

NamePayloadDescription
point-click(point: IChartPoint, event: MouseEvent | KeyboardEvent)Click or keyboard activation on a data point.
legend-click(series: IChartSeries, index: number)Click on a legend entry.
series-toggle(series: IChartSeries, visible: boolean)Visibility flip after a legend click.

Slots ​

NameBindingsDescription
tooltip{ point: IChartPoint, series: IChartSeries, category: string | number }Replace the default tooltip body.
legend-item{ series: IChartSeries, index: number, visible: boolean }Replace one legend entry.
title—Replace the title + subtitle block.
empty—Rendered when series is empty or every series is hidden.

Behaviour notes ​

Responsive drawing surface (#1317). The SVG viewBox follows the measured box of the chart (useChartSize, a ResizeObserver), not a fixed 600 × 360. The plot fills the container width, scales are recomputed, and text, strokes and markers keep their real pixel size instead of being scaled with the viewBox. Until measured (SSR, first paint) the 600 × 360 fallback is used, so hydration is unchanged. With an auto-height container the 5:3 ratio is kept; give the chart a height / aspectRatio to change it.

X-axis label decimation (#1325). When the X tick labels would touch (narrow container, large font), only one label in N is shown: N comes from the widest label and the smallest spacing between ticks. After mount the width is MEASURED (getComputedTextLength) and re-measured whenever the ticks change (which follows the container width and the categories); on the server and before the first measure it is ESTIMATED (CHART_AXIS_LABEL_CHAR_WIDTH per character plus CHART_AXIS_LABEL_MIN_GAP), so the initial markup is identical on both sides. Text stays horizontal and complete (no rotation, no truncation). Skipped labels stay in the DOM with visibility="hidden" and aria-hidden (they must remain measurable); the value of every data point stays available on hover and focus through the point's accessible label.

Topology primer.

typeShape emittedSmoothing applies
linePolyline per series + circle markersYes ('curve' or 'monotone')
areaFilled polygon + stroke per series + markersYes
splinePolyline per series, defaults to 'monotone' smoothingYes (overridable)
stepped-lineRight-angle staircase per series + markersNo
columnVertical <rect> per data pointN/A
barHorizontal <rect> per data pointN/A
scatter<circle> per data point, no connecting pathN/A

spline smoothing override. spline calls the monotone path generator by default. Pass smoothing='curve' to switch to Catmull-Rom, or smoothing='none' to collapse back to straight segments (at which point it is identical to line).

Stacked bar / column. stacked=true accumulates series values per data index. The Y scale is computed over the stacked totals — the global yMin / yMax overrides still apply after stacking. Stacking on line, area, or scatter has no visual effect.

Keyboard (#1333). The chart is a single tab stop (roving tabindex): Tab enters it once on the last active point, Tab leaves it. ArrowRight / ArrowLeft move along the series, ArrowDown / ArrowUp move to the next / previous series at the same position (clamped when the series is shorter), Home / End jump to the first / last point, Enter / Space fire point-click. The zoom-reset button keeps its own tab stop. Full table in the OrigamChart page.

Accessibility — drilldown & zoom. drilldown.navAriaLabel and zoomResetLabel carry locale keys, not final text — they resolve through the DS t() mechanism, so the breadcrumb <nav> and the "Reset zoom" control follow the active locale out of the box. Since #764 the button's VISIBLE text reads the same key as its aria-label; before that fix only the accessible name was translated, and the two halves of the same control disagreed in every non-English locale. A raw string that matches no key is returned unchanged, so a literal override (zoomResetLabel="Reset the view") still works for consumers who prefer to translate on their side.

Mix charts. Each series can set its own type to override the chart-level type. A common pattern: a column chart with a line overlay on top. The series-level type must be a TChartType value; there is no restriction to cartesian-only values at the series level, but using polar or gauge types on a series in a cartesian chart has undefined behaviour.

Scatter data shape. scatter requires explicit {x, y} objects in series[n].data. Number-only data is technically accepted but all points land on the same X position since there is no implicit category axis.

Examples ​

Minimal line chart ​

vue
<template>
  <origam-chart-cartesian
    type="line"
    :series="series"
    :categories="['Q1', 'Q2', 'Q3', 'Q4']"
    :height="240"
    title="Quarterly revenue"
  />
</template>

<script setup lang="ts">
import { OrigamChartCartesian } from '@origam/ds'
import type { IChartSeries } from '@origam/ds'

const series: Array<IChartSeries> = [
  { name: 'Revenue', data: [120, 185, 210, 250], color: 'primary' },
  { name: 'Costs',   data: [ 90, 130, 155, 175], color: 'danger'  }
]
</script>

Stacked column with custom palette and Y formatter ​

vue
<template>
  <origam-chart-cartesian
    type="column"
    :series="series"
    :categories="months"
    :color-scheme="['#8b5cf6', '#ec4899', '#f97316', '#22c55e', '#0ea5e9']"
    :stacked="true"
    :y-axis-format="formatRevenue"
    :height="360"
    title="Product mix"
    legend-position="right"
  />
</template>

<script setup lang="ts">
import { OrigamChartCartesian } from '@origam/ds'
import type { IChartSeries } from '@origam/ds'

const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
                 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

const series: Array<IChartSeries> = [
  { name: 'Product A', data: [10, 14, 18, 16, 22, 28, 25, 30, 33, 36, 38, 42] },
  { name: 'Product B', data: [ 6, 10, 14, 12, 18, 22, 19, 24, 28, 30, 32, 35] },
  { name: 'Product C', data: [ 4,  6, 10,  9, 13, 16, 14, 18, 21, 23, 25, 28] }
]

function formatRevenue(v: number) {
  return `$${v}k`
}
</script>

Mix chart — column + line overlay ​

vue
<template>
  <origam-chart-cartesian
    type="column"
    :series="series"
    :categories="months"
    :height="320"
    title="Revenue with overlay"
  />
</template>

<script setup lang="ts">
import { OrigamChartCartesian } from '@origam/ds'
import type { IChartSeries } from '@origam/ds'

const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun']

const series: Array<IChartSeries> = [
  { name: 'Revenue', data: [90, 105, 118, 112, 132, 155], color: 'primary' },
  { name: 'Trend',   data: [88, 102, 116, 114, 134, 158], color: 'warning', type: 'line' }
]
</script>