Skip to content
WebJs
Menu

Beautiful charts, rendered on the server as SVG. Copy and paste into your apps.

Bar Chart - Interactive
Showing total visitors for the last 3 months
Apr 1Apr 2Apr 3Apr 4Apr 5Apr 6Apr 7Apr 8Apr 9Apr 10Apr 11Apr 12Apr 13Apr 14Apr 15Apr 16Apr 17Apr 18Apr 19Apr 20Apr 21Apr 22Apr 23Apr 24Apr 25Apr 26Apr 27Apr 28Apr 29Apr 30

Introducing Charts. A collection of chart components that you can copy and paste into your apps.

Charts are designed to look great out of the box. They work well with the other components and are fully customizable to fit your project.

Browse the Charts Library.

Component

The charts are drawn on the server as plain SVG, with no charting library. The layout engine computes the margins, scales, curves, bar layout and tick thinning on the server, and every option below shapes what it draws.

We designed the chart component with composition in mind. Each chart is one function call, with the grid, the axes, the tooltip and the legend as options you add only when and where you need them.

import { html } from '@webjsdev/core';
import { barChart } from '#components/ui/chart.ts';

export function myChart() {
  return html`
    ${barChart({
      config: chartConfig,
      data,
      bars: [{ dataKey: 'value' }],
      tooltip: {},
    })}
  `;
}

The first paint is the whole chart, so it reads with JavaScript off. The <ui-chart> element the function returns adds the tooltip, the hover cursor and the keyboard once it loads.

The components are yours. The three files add chart writes are plain source in your app.

Installation

pnpm dlx @webjsdev/ui add chart

Your First Chart

Let's build your first chart. We'll build a bar chart, add a grid, axis, tooltip and legend.

Start by defining your data

The following data represents the number of desktop and mobile users for each month.

Note: Your data can be in any shape. You are not limited to the shape of the data below. Use the dataKey option to map your data to the chart.

components/example-chart.ts
const chartData = [
  { month: 'January', desktop: 186, mobile: 80 },
  { month: 'February', desktop: 305, mobile: 200 },
  { month: 'March', desktop: 237, mobile: 120 },
  { month: 'April', desktop: 73, mobile: 190 },
  { month: 'May', desktop: 209, mobile: 130 },
  { month: 'June', desktop: 214, mobile: 140 },
];

Define your chart config

The chart config holds configuration for the chart. This is where you place human-readable strings, such as labels, icons and color tokens for theming.

components/example-chart.ts
import type { ChartConfig } from '#components/ui/chart.ts';

const chartConfig = {
  desktop: {
    label: 'Desktop',
    color: '#2563eb',
  },
  mobile: {
    label: 'Mobile',
    color: '#60a5fa',
  },
} satisfies ChartConfig;

Build your chart

You can now build your chart with barChart().

Important: Keep a height, a min-h-[VALUE] or an aspect-* class on the chart. The SVG scales to the box its container gives it.

import { html } from '@webjsdev/core';
import { barChart, type ChartConfig } from '#components/ui/chart.ts';

export const description = 'A bar chart';

const chartData = [
  { month: 'January', desktop: 186, mobile: 80 },
  { month: 'February', desktop: 305, mobile: 200 },
  { month: 'March', desktop: 237, mobile: 120 },
  { month: 'April', desktop: 73, mobile: 190 },
  { month: 'May', desktop: 209, mobile: 130 },
  { month: 'June', desktop: 214, mobile: 140 },
];

const chartConfig = {
  desktop: {
    label: 'Desktop',
    color: '#2563eb',
  },
  mobile: {
    label: 'Mobile',
    color: '#60a5fa',
  },
} satisfies ChartConfig;

export default function ChartExample() {
  return html`
    ${barChart({
      config: chartConfig,
      data: chartData,
      class: 'min-h-[200px] w-full',
      title: 'Desktop and mobile visitors, January to June',
      bars: [
        { dataKey: 'desktop', fill: 'var(--color-desktop)', radius: 4 },
        { dataKey: 'mobile', fill: 'var(--color-mobile)', radius: 4 },
      ],
    })}
  `;
}
View Code

Add a Grid

Let's add a grid to the chart.

Add the grid option to your chart.

${barChart({
  config: chartConfig,
  data: chartData,
  class: 'min-h-[200px] w-full',
  grid: { vertical: false },
  bars: [
    { dataKey: 'desktop', fill: 'var(--color-desktop)', radius: 4 },
    { dataKey: 'mobile', fill: 'var(--color-mobile)', radius: 4 },
  ],
})}
import { html } from '@webjsdev/core';
import { barChart, type ChartConfig } from '#components/ui/chart.ts';

export const description = 'A bar chart with a grid';

const chartData = [
  { month: 'January', desktop: 186, mobile: 80 },
  { month: 'February', desktop: 305, mobile: 200 },
  { month: 'March', desktop: 237, mobile: 120 },
  { month: 'April', desktop: 73, mobile: 190 },
  { month: 'May', desktop: 209, mobile: 130 },
  { month: 'June', desktop: 214, mobile: 140 },
];

const chartConfig = {
  desktop: {
    label: 'Desktop',
    color: '#2563eb',
  },
  mobile: {
    label: 'Mobile',
    color: '#60a5fa',
  },
} satisfies ChartConfig;

export default function ChartBarDemoGrid() {
  return html`
    ${barChart({
      config: chartConfig,
      data: chartData,
      class: 'min-h-[200px] w-full',
      title: 'Desktop and mobile visitors, January to June',
      grid: { vertical: false },
      bars: [
        { dataKey: 'desktop', fill: 'var(--color-desktop)', radius: 4 },
        { dataKey: 'mobile', fill: 'var(--color-mobile)', radius: 4 },
      ],
    })}
  `;
}
View Code

Add an Axis

To add an x-axis to the chart, we'll use the xAxis option.

Add the xAxis option to your chart.

${barChart({
  config: chartConfig,
  data: chartData,
  class: 'h-[200px] w-full',
  grid: { vertical: false },
  xAxis: {
    dataKey: 'month',
    tickLine: false,
    tickMargin: 10,
    axisLine: false,
    tickFormatter: (value) => String(value).slice(0, 3),
  },
  bars: [
    { dataKey: 'desktop', fill: 'var(--color-desktop)', radius: 4 },
    { dataKey: 'mobile', fill: 'var(--color-mobile)', radius: 4 },
  ],
})}
JanFebMarAprMayJun
import { html } from '@webjsdev/core';
import { barChart, type ChartConfig } from '#components/ui/chart.ts';

export const description = 'A bar chart with a grid and an x axis';

const chartData = [
  { month: 'January', desktop: 186, mobile: 80 },
  { month: 'February', desktop: 305, mobile: 200 },
  { month: 'March', desktop: 237, mobile: 120 },
  { month: 'April', desktop: 73, mobile: 190 },
  { month: 'May', desktop: 209, mobile: 130 },
  { month: 'June', desktop: 214, mobile: 140 },
];

const chartConfig = {
  desktop: {
    label: 'Desktop',
    color: '#2563eb',
  },
  mobile: {
    label: 'Mobile',
    color: '#60a5fa',
  },
} satisfies ChartConfig;

export default function ChartBarDemoAxis() {
  return html`
    ${barChart({
      config: chartConfig,
      data: chartData,
      class: 'min-h-[200px] w-full',
      title: 'Desktop and mobile visitors, January to June',
      grid: { vertical: false },
      xAxis: { dataKey: 'month', tickLine: false, tickMargin: 10, axisLine: false, tickFormatter: (value) => String(value).slice(0, 3) },
      bars: [
        { dataKey: 'desktop', fill: 'var(--color-desktop)', radius: 4 },
        { dataKey: 'mobile', fill: 'var(--color-mobile)', radius: 4 },
      ],
    })}
  `;
}
View Code

Add Tooltip

So far the chart is static SVG. It looks great out of the box thanks to the chart's container classes.

To add a tooltip, we'll use the tooltip option, which draws the kit's tooltip card.

Add the tooltip option to your chart.

${barChart({
  config: chartConfig,
  data: chartData,
  class: 'h-[200px] w-full',
  grid: { vertical: false },
  xAxis: {
    dataKey: 'month',
    tickLine: false,
    tickMargin: 10,
    axisLine: false,
    tickFormatter: (value) => String(value).slice(0, 3),
  },
  tooltip: {},
  bars: [
    { dataKey: 'desktop', fill: 'var(--color-desktop)', radius: 4 },
    { dataKey: 'mobile', fill: 'var(--color-mobile)', radius: 4 },
  ],
})}
JanFebMarAprMayJun
import { html } from '@webjsdev/core';
import { barChart, type ChartConfig } from '#components/ui/chart.ts';

export const description = 'A bar chart with a tooltip';

const chartData = [
  { month: 'January', desktop: 186, mobile: 80 },
  { month: 'February', desktop: 305, mobile: 200 },
  { month: 'March', desktop: 237, mobile: 120 },
  { month: 'April', desktop: 73, mobile: 190 },
  { month: 'May', desktop: 209, mobile: 130 },
  { month: 'June', desktop: 214, mobile: 140 },
];

const chartConfig = {
  desktop: {
    label: 'Desktop',
    color: '#2563eb',
  },
  mobile: {
    label: 'Mobile',
    color: '#60a5fa',
  },
} satisfies ChartConfig;

export default function ChartBarDemoTooltip() {
  return html`
    ${barChart({
      config: chartConfig,
      data: chartData,
      class: 'min-h-[200px] w-full',
      title: 'Desktop and mobile visitors, January to June',
      grid: { vertical: false },
      xAxis: { dataKey: 'month', tickLine: false, tickMargin: 10, axisLine: false, tickFormatter: (value) => String(value).slice(0, 3) },
      tooltip: {},
      bars: [
        { dataKey: 'desktop', fill: 'var(--color-desktop)', radius: 4 },
        { dataKey: 'mobile', fill: 'var(--color-mobile)', radius: 4 },
      ],
    })}
  `;
}
View Code

Hover to see the tooltips. Easy, right? One option, and we've got a beautiful tooltip.

Add Legend

We'll do the same for the legend, with the legend option, which draws the kit's legend.

Add the legend option to your chart.

${barChart({
  config: chartConfig,
  data: chartData,
  class: 'h-[200px] w-full',
  grid: { vertical: false },
  xAxis: {
    dataKey: 'month',
    tickLine: false,
    tickMargin: 10,
    axisLine: false,
    tickFormatter: (value) => String(value).slice(0, 3),
  },
  tooltip: {},
  legend: {},
  bars: [
    { dataKey: 'desktop', fill: 'var(--color-desktop)', radius: 4 },
    { dataKey: 'mobile', fill: 'var(--color-mobile)', radius: 4 },
  ],
})}
JanFebMarAprMayJun
Desktop
Mobile
import { html } from '@webjsdev/core';
import { barChart, type ChartConfig } from '#components/ui/chart.ts';

export const description = 'A bar chart with a tooltip and a legend';

const chartData = [
  { month: 'January', desktop: 186, mobile: 80 },
  { month: 'February', desktop: 305, mobile: 200 },
  { month: 'March', desktop: 237, mobile: 120 },
  { month: 'April', desktop: 73, mobile: 190 },
  { month: 'May', desktop: 209, mobile: 130 },
  { month: 'June', desktop: 214, mobile: 140 },
];

const chartConfig = {
  desktop: {
    label: 'Desktop',
    color: '#2563eb',
  },
  mobile: {
    label: 'Mobile',
    color: '#60a5fa',
  },
} satisfies ChartConfig;

export default function ChartBarDemoLegend() {
  return html`
    ${barChart({
      config: chartConfig,
      data: chartData,
      class: 'min-h-[200px] w-full',
      title: 'Desktop and mobile visitors, January to June',
      grid: { vertical: false },
      xAxis: { dataKey: 'month', tickLine: false, tickMargin: 10, axisLine: false, tickFormatter: (value) => String(value).slice(0, 3) },
      tooltip: {},
      legend: {},
      bars: [
        { dataKey: 'desktop', fill: 'var(--color-desktop)', radius: 4 },
        { dataKey: 'mobile', fill: 'var(--color-mobile)', radius: 4 },
      ],
    })}
  `;
}
View Code

Done. You've built your first chart! What's next?

Chart Config

The chart config is where you define the labels, icons and colors for a chart.

It is intentionally decoupled from chart data.

This allows you to share config and color tokens between charts. It can also work independently for cases where your data or color tokens live remotely or in a different format.

import { MonitorIcon } from '#lib/utils/icons.ts';
import type { ChartConfig } from '#components/ui/chart.ts';

const chartConfig = {
  desktop: {
    label: 'Desktop',
    // A function returning an html or svg template.
    icon: () => MonitorIcon(),
    // A color like 'hsl(220, 98%, 61%)' or 'var(--color-name)'
    color: '#2563eb',
    // OR a theme object with 'light' and 'dark' keys
    theme: {
      light: '#2563eb',
      dark: '#dc2626',
    },
  },
} satisfies ChartConfig;

Theming

Charts have built-in support for theming. You can use css variables (recommended) or color values in any color format, such as hex, hsl or oklch.

CSS Variables

Define your colors in your css file

app/globals.css
@layer base {
  :root {
    --chart-1: oklch(0.646 0.222 41.116);
    --chart-2: oklch(0.6 0.118 184.704);
  }

  .dark {
    --chart-1: oklch(0.488 0.243 264.376);
    --chart-2: oklch(0.696 0.17 162.48);
  }
}

Add the color to your chartConfig

components/example-chart.ts
const chartConfig = {
  desktop: {
    label: 'Desktop',
    color: 'var(--chart-1)',
  },
  mobile: {
    label: 'Mobile',
    color: 'var(--chart-2)',
  },
} satisfies ChartConfig;

hex, hsl or oklch

You can also define your colors directly in the chart config. Use the color format you prefer.

components/example-chart.ts
const chartConfig = {
  desktop: {
    label: 'Desktop',
    color: '#2563eb',
  },
  mobile: {
    label: 'Mobile',
    color: 'hsl(220, 98%, 61%)',
  },
  tablet: {
    label: 'Tablet',
    color: 'oklch(0.5 0.2 240)',
  },
  laptop: {
    label: 'Laptop',
    color: 'var(--chart-2)',
  },
} satisfies ChartConfig;

Using Colors

To use the theme colors in your chart, reference the colors using the format var(--color-KEY). The chart sets one such variable per config entry on its container.

Components

bars: [{ dataKey: 'desktop', fill: 'var(--color-desktop)' }]

Chart Data

components/example-chart.ts
const chartData = [
  { browser: 'chrome', visitors: 275, fill: 'var(--color-chrome)' },
  { browser: 'safari', visitors: 200, fill: 'var(--color-safari)' },
];

Tailwind

components/example-chart.ts
labels: [{ class: 'fill-(--color-desktop)' }]

Tooltip

A chart tooltip contains a label, name, indicator and value. You can use a combination of these to customize your tooltip.

Label
Page Views
Desktop
186
Mobile
80
Name
Chrome
1,286
Firefox
1,000
Page Views
Desktop
12,486
Indicator
Chrome
1,286

You can turn on/off any of these using the hideLabel, hideIndicator options and customize the indicator style using the indicator option.

Use labelKey and nameKey to use a custom key for the tooltip label and name.

Every chart function takes a tooltip option. Pass it to add the tooltip to your chart.

components/example-chart.ts
tooltip: {}

The tooltip for each point is resolved on the server, so a labelFormatter, a formatter or a config icon runs there and never ships to the browser.

Props

Use the following options to customize the tooltip.

OptionTypeDescription
labelKeystringThe config or data key to use for the label.
nameKeystringThe config or data key to use for the name.
indicatordot line or dashedThe indicator style for the tooltip.
hideLabelbooleanWhether to hide the label.
hideIndicatorbooleanWhether to hide the indicator.

Colors

Colors are automatically referenced from the chart config.

Custom

To use a custom key for tooltip label and names, use the labelKey and nameKey options.

const chartData = [
  { browser: 'chrome', visitors: 187, fill: 'var(--color-chrome)' },
  { browser: 'safari', visitors: 200, fill: 'var(--color-safari)' },
];

const chartConfig = {
  visitors: {
    label: 'Total Visitors',
  },
  chrome: {
    label: 'Chrome',
    color: 'var(--chart-1)',
  },
  safari: {
    label: 'Safari',
    color: 'var(--chart-2)',
  },
} satisfies ChartConfig;
components/example-chart.ts
tooltip: { labelKey: 'visitors', nameKey: 'browser' }

This will use Total Visitors for label and Chrome and Safari for the tooltip names.

Legend

Every chart function takes a legend option. Pass it to add a legend to your chart.

components/example-chart.ts
legend: {}

Colors

Colors are automatically referenced from the chart config.

Custom

To use a custom key for legend names, use the nameKey option.

const chartData = [
  { browser: 'chrome', visitors: 187, fill: 'var(--color-chrome)' },
  { browser: 'safari', visitors: 200, fill: 'var(--color-safari)' },
];

const chartConfig = {
  chrome: {
    label: 'Chrome',
    color: 'var(--chart-1)',
  },
  safari: {
    label: 'Safari',
    color: 'var(--chart-2)',
  },
} satisfies ChartConfig;
components/example-chart.ts
legend: { nameKey: 'browser' }

This will use Chrome and Safari for the legend names.

Accessibility

A chart with a tooltip has an accessible layer by default, the accessibilityLayer option: it takes focus, the arrow keys step through its points, Home and End jump to the first and last, Escape hides the tooltip, and each step is announced to screen readers. Pass accessibilityLayer: false to turn it off.

Give every chart a title, which names it for screen readers, and keep its numbers in the text around it for a reader who cannot use the chart.

components/example-chart.ts
${lineChart({ config, data, title: 'Visitors by month', tooltip: {}, lines })}

RTL

To enable RTL support, see the RTL configuration guide. The legend and the tooltip follow the dir attribute, and reversed on the x axis runs the categories from the right.

ينافبرمارأبرماييون
سطح المكتب
الجوال
import { html } from '@webjsdev/core';
import { barChart, type ChartConfig } from '#components/ui/chart.ts';

export const description = 'A bar chart, right to left';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      january: 'January',
      february: 'February',
      march: 'March',
      april: 'April',
      may: 'May',
      june: 'June',
      desktop: 'Desktop',
      mobile: 'Mobile',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      january: 'يناير',
      february: 'فبراير',
      march: 'مارس',
      april: 'أبريل',
      may: 'مايو',
      june: 'يونيو',
      desktop: 'سطح المكتب',
      mobile: 'الجوال',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      january: 'ינואר',
      february: 'פברואר',
      march: 'מרץ',
      april: 'אפריל',
      may: 'מאי',
      june: 'יוני',
      desktop: 'מחשב',
      mobile: 'נייד',
    },
  },
} as const;

const chartData = [
  { month: 'january', desktop: 186, mobile: 80 },
  { month: 'february', desktop: 305, mobile: 200 },
  { month: 'march', desktop: 237, mobile: 120 },
  { month: 'april', desktop: 73, mobile: 190 },
  { month: 'may', desktop: 209, mobile: 130 },
  { month: 'june', desktop: 214, mobile: 140 },
];

// The provider is the dir attribute: the legend and the tooltip are HTML and
// follow it, and the x axis is reversed so January starts on the right.
export default function ChartRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];
  const label = (value: unknown) => t[value as keyof typeof t] ?? String(value);

  const chartConfig = {
    desktop: {
      label: t.desktop,
      color: 'var(--chart-2)',
    },
    mobile: {
      label: t.mobile,
      color: 'var(--chart-1)',
    },
  } satisfies ChartConfig;

  return html`
    <div dir=${dir} lang=${lang} class="w-full">
      ${barChart({
        config: chartConfig,
        data: chartData,
        class: 'min-h-[200px] w-full',
        grid: { vertical: false },
        xAxis: {
          dataKey: 'month',
          tickLine: false,
          tickMargin: 10,
          axisLine: false,
          tickFormatter: (value) => label(value).slice(0, 3),
          reversed: dir === 'rtl',
        },
        tooltip: { labelFormatter: (value) => label(value), labelClass: 'w-32' },
        legend: {},
        bars: [
          { dataKey: 'desktop', fill: 'var(--color-desktop)', radius: 4 },
          { dataKey: 'mobile', fill: 'var(--color-mobile)', radius: 4 },
        ],
      })}
    </div>
  `;
}
View Code