How to Use

Chart

Chart renders SVG-based data visualizations with support for six chart types: line, area, bar, column, pie, and donut. The component handles all rendering internally — you provide structured data as an array of objects, specify which property maps to the X-axis (xKey) and which properties map to the Y-axis series (yKeys), and the component generates a responsive SVG chart with tooltips, legends, grid lines, and zoom/pan controls. Each chart type uses the same data structure — only the type prop changes, making it easy to switch between visualizations for the same dataset. Charts support multi-series data (multiple yKeys), custom colors per series, toggleable tooltips and legends, configurable height, and dark mode adaptation via CSS variables.

import {Chart} from "oks-ui"

Basic Line Chart

The simplest chart requires three props: type (defaults to "line"), data (an array of objects), xKey (the object key for X-axis labels), and yKeys (an array of series definitions with key — the object key for Y-axis values — and name — the series label for the legend and tooltip). Line charts are best for showing trends over continuous data like time series, months, or sequential stages. The chart renders a responsive SVG that scales to its container width. Set height to control the chart's pixel height.

const salesData = [
  { month: "Jan", revenue: 12000 },
  { month: "Feb", revenue: 19000 },
  { month: "Mar", revenue: 15000 },
  { month: "Apr", revenue: 22000 },
  { month: "May", revenue: 28000 },
  { month: "Jun", revenue: 24000 },
];

<Chart
  type="line"
  data={salesData}
  xKey="month"
  yKeys={[{ key: "revenue", name: "Revenue" }]}
  height={300}
/>

Multi-Series Comparison

Add multiple entries to yKeys to compare several data series on the same chart. Each series receives a distinct color automatically. Multi-series charts are useful for comparing revenue vs. profit, actual vs. target, or any scenario where you need to visualize multiple metrics side by side. Each series gets its own entry in the legend and tooltip, making it easy for users to distinguish between lines, bars, or areas.

const data = [
  { month: "Jan", revenue: 12000, profit: 4000 },
  { month: "Feb", revenue: 19000, profit: 7000 },
  { month: "Mar", revenue: 15000, profit: 5500 },
  { month: "Apr", revenue: 22000, profit: 8500 },
];

<Chart
  type="column"
  data={data}
  xKey="month"
  yKeys={[
    { key: "revenue", name: "Revenue" },
    { key: "profit", name: "Profit" },
  ]}
  height={300}
/>

Pie and Donut Charts

Pie and donut charts display proportional data as circle sectors. The xKey is the label for each segment, and yKeys contain the numeric value. The pie chart fills a full circle with colored sectors; the donut chart has a hollow center, which can display a total or summary value. Both types are ideal for showing percentages, market share, survey results, or budget allocation. Values do not need to sum to 100 — the chart calculates percentages automatically.

const segments = [
  { name: "Chrome", value: 45 },
  { name: "Firefox", value: 25 },
  { name: "Edge", value: 20 },
  { name: "Safari", value: 10 },
];

<Chart type="pie" data={segments} xKey="name" yKeys={[{ key: "value", name: "Users" }]} height={300} />
<Chart type="donut" data={segments} xKey="name" yKeys={[{ key: "value", name: "Users" }]} height={300} />

Custom Colors and Display Options

Override the default series color by passing a color property in the yKeys entry (supports hex, rgb, hsl, or CSS variable references). Control the chart's visual elements with boolean props: showLegend toggles the legend, showTooltip enables hover tooltips showing series name and value, showGrid displays background grid lines. These can be individually toggled to match your design — for example, hide the grid for a cleaner minimal look, or hide the legend when there's only one series.

<Chart
  type="area"
  data={data}
  xKey="month"
  yKeys={[{
    key: "revenue",
    name: "Revenue",
    color: "#7c3aed"
  }]}
  showLegend
  showTooltip
  showGrid
  height={350}
/>

Chart Type Selection Guide

Choose the chart type based on your data and the story you want to tell. "line" is best for showing trends and changes over time — use it for revenue, user growth, or stock prices over months/years. "area" extends the line chart by filling the area below the line — use it to emphasize volume or magnitude behind a trend. "bar" renders horizontal bars for comparing categories (great for long category names or many categories). "column" renders vertical columns — classic for comparing values across categories with short labels. "pie" and "donut" show how a whole breaks into parts — use them for market share, survey responses, or budget allocation. All chart types share the same data and props structure — only the type prop changes.

Accessibility

Charts are rendered as SVG elements. The component assigns a role="img" to the SVG and sets an aria-label based on the chart data. Tooltips provide hover-based value readouts. For critical data visualizations, provide a text-based data table or summary below the chart as a fallback for screen readers. The chart respects prefers-reduced-motion by disabling animations. Colors are customizable to meet contrast requirements — ensure sufficient contrast between series colors and the background.

Props Reference

All available props for Chart. See the full API reference page for interactive playground examples.

Prop	Type	Default	Description
type	"line" \| "area" \| "bar" \| "column" \| "pie" \| "donut"	`"line"`	Chart type.
data	Record<string, any>[]	`—`	Array of data objects.
xKey	string	`—`	Key for X-axis values.
yKeys	{ key: string; name: string; color?: string }[]	`—`	Y-axis series definitions.
showLegend	boolean	`true`	Show the chart legend.
showTooltip	boolean	`true`	Show tooltips on hover.
height	number	`300`	Chart height in pixels.
showGrid	boolean	`true`	Show grid lines.

Best Practices

◆All 6 chart types use the same data structure and props — only change the type prop to switch between line, area, bar, column, pie, and donut
◆For time-series data with many points (50+), use line or area charts — they handle dense data better than bar/column
◆Pie and donut charts work best with 3-7 segments; more than 7 makes individual slices hard to distinguish
◆Use multi-series yKeys to compare revenue vs. cost, actual vs. target, or this year vs. last year on the same chart
◆The chart is responsive — it automatically resizes to fit its container; no manual width configuration needed
◆Custom colors via yKeys[].color override the default palette — useful for brand matching or highlighting a specific series
◆For zoom and pan interactions, set enableZoom and enablePan props (see full API reference)
◆The chart supports export to SVG and PNG — see the export prop in the full API reference

View full API reference for Chart →