Chart

Introducing Charts: A curated collection of chart components meticulously crafted for seamless integration into your applications. These components are designed not just for visual appeal right out of the box, but also for harmonious coexistence with other UI elements and deep customization potential to match your project's unique aesthetic and functional requirements.

Explore the full range of available chart types and examples in the dedicated Charts Library.

Core Chart Component Philosophy

Our charting solution leverages the powerful and widely-adopted Recharts library as its foundation.

The core design principle is composition over configuration. Instead of providing a monolithic chart component, we encourage you to build your charts using standard Recharts components (<BarChart>, <Line>, <XAxis>, etc.). You then enhance these standard charts by incorporating our custom components, like <ChartContainer>, <ChartTooltip>, and <ChartLegend>, precisely when needed for styling, interactivity, or specific features.

export function MyChart() {
  return (
    <ChartContainer>
      <BarChart data={data}>
        <Bar dataKey="value" />
        <ChartTooltip content={<ChartTooltipContent />} />
      </BarChart>
    </ChartContainer>
  );
}

Crucially, we do not abstract away Recharts. This direct approach ensures you're never locked into a limiting wrapper. When new features or versions of Recharts are released, you can adopt them directly by following the official Recharts documentation and upgrade paths. This philosophy empowers you with full control and flexibility.

Ultimately, the chart components become integral parts of your codebase, fully owned and adaptable by you.

Installation Guide

npx shadcn@latest add chart

@layer base {
  :root {
    --chart-1: 12 76% 61%;
    --chart-2: 173 58% 39%;
    --chart-3: 197 37% 24%;
    --chart-4: 43 74% 66%;
    --chart-5: 27 87% 67%;
  }

  .dark {
    --chart-1: 220 70% 50%;
    --chart-2: 160 60% 45%;
    --chart-3: 30 80% 55%;
    --chart-4: 280 65% 60%;
    --chart-5: 340 75% 55%;
  }
}

Building Your First Chart: Step-by-Step

Let's walk through the process of creating a fundamental chart. We'll construct a bar chart, progressively enhancing it with essential elements like a grid, axes, an interactive tooltip, and a descriptive 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 },
];

import { type ChartConfig } from "@/components/ui/chart";

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

Enhancing Readability: Adding a Grid

Grid lines can significantly improve the readability of chart values. Let's incorporate a horizontal grid using the Recharts CartesianGrid component.

import { Bar, BarChart, CartesianGrid } from "recharts";

<ChartContainer config={chartConfig} className="min-h-[200px] w-full">
  <BarChart accessibilityLayer data={chartData}>
    <CartesianGrid vertical={false} />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
  </BarChart>
</ChartContainer>

Providing Context: Adding Axes

Axes provide crucial context by labeling the data dimensions. We'll add an x-axis to display the months using the Recharts XAxis component. A y-axis could be added similarly using YAxis.

import { Bar, BarChart, CartesianGrid, XAxis } from "recharts";

<ChartContainer config={chartConfig} className="h-[200px] w-full">
  <BarChart accessibilityLayer data={chartData}>
    <CartesianGrid vertical={false} />
    <XAxis
      dataKey="month"
      tickLine={false}
      tickMargin={10}
      axisLine={false}
      tickFormatter={(value) => value.slice(0, 3)}
    />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
  </BarChart>
</ChartContainer>

Interactive Data: Adding Tooltips

Up to this point, we've utilized standard Recharts components, benefiting from the baseline styling provided by our chart setup.

To introduce interactivity and display detailed data on hover, we'll integrate our custom <ChartTooltip> and <ChartTooltipContent> components. These provide styled, configurable tooltips consistent with the overall UI theme.

import { ChartTooltip, ChartTooltipContent } from "@/components/ui/chart";

<ChartContainer config={chartConfig} className="h-[200px] w-full">
  <BarChart accessibilityLayer data={chartData}>
    <CartesianGrid vertical={false} />
    <XAxis
      dataKey="month"
      tickLine={false}
      tickMargin={10}
      axisLine={false}
      tickFormatter={(value) => value.slice(0, 3)}
    />
    <ChartTooltip content={<ChartTooltipContent />} />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
  </BarChart>
</ChartContainer>

Identifying Data Series: Adding a Legend

For charts displaying multiple data series (like our desktop vs. mobile data), a legend is essential for identification. We'll use the custom <ChartLegend> and <ChartLegendContent> components for a themed legend.

import { ChartLegend, ChartLegendContent } from "@/components/ui/chart";

<ChartContainer config={chartConfig} className="h-[200px] w-full">
  <BarChart accessibilityLayer data={chartData}>
    <CartesianGrid vertical={false} />
    <XAxis
      dataKey="month"
      tickLine={false}
      tickMargin={10}
      axisLine={false}
      tickFormatter={(value) => value.slice(0, 3)}
    />
    <ChartTooltip content={<ChartTooltipContent />} />
    <ChartLegend content={<ChartLegendContent />} />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
  </BarChart>
</ChartContainer>

Congratulations! You've successfully constructed your first chart, incorporating essential elements for clarity and interactivity. Where to go from here?

• Themes and Colors

• Tooltip

• Legend

Centralized Chart Configuration

The chartConfig object acts as a central repository for metadata related to your chart's data series, distinct from the raw data itself.

This deliberate separation offers several advantages:

• Reusability: Share the same configuration (labels, icons, colors) across multiple charts displaying similar data.

• Flexibility: Manage display properties independently, even if your data structure changes or color definitions are sourced externally (e.g., from an API or theme file).

• Clarity: Keep data structures clean and focused on values, while chartConfig handles presentation details.

Define labels, associate icons (using libraries like lucide-react), and specify colors using CSS variables or direct values.

import { Monitor } from "lucide-react";

import { type ChartConfig } from "@/components/ui/chart";

const chartConfig = {
  desktop: {
    label: "Desktop",
    icon: Monitor,
    color: "#2563eb",
    theme: {
      light: "#2563eb",
      dark: "#dc2626",
    },
  },
} satisfies ChartConfig;

Customizing Appearance: Theming

Our chart components are designed with theming flexibility in mind. You can define colors using standard CSS variables (the recommended approach for consistency and adaptability with light/dark modes) or by providing direct color values in various formats (hex, hsl, oklch).

Theming with CSS Variables (Recommended)

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 240 10% 3.9%;
    // ...
    --chart-1: 12 76% 61%;
    --chart-2: 173 58% 39%;
  }

  .dark: {
    --background: 240 10% 3.9%;
    --foreground: 0 0% 100%;
    // ...
    --chart-1: 220 70% 50%;
    --chart-2: 160 60% 45%;
  }
}

const chartConfig = {
  desktop: {
    label: "Desktop",
    color: "hsl(var(--chart-1))",
  },
  mobile: {
    label: "Mobile",
    color: "hsl(var(--chart-2))",
  },
} satisfies ChartConfig;

--chart-1: oklch(70% 0.227 154.59);

color: "var(--chart-1)",

Theming with Direct Color Values

Alternatively, you can specify colors directly within the chartConfig using any valid CSS color format (hexadecimal, HSL, OKLCH, etc.). This might be simpler for smaller projects or when CSS variables aren't being used extensively.

const chartConfig = {
  desktop: {
    label: "Desktop",
    color: "#2563eb",
  },
} satisfies ChartConfig;

Applying Theme Colors

Once colors are defined in your chartConfig (either via CSS variables or direct values), apply them within your Recharts components using the var(--color-KEY) syntax, where KEY corresponds to the key defined in your chartConfig (e.g., desktop, mobile).

Components

<Bar dataKey="desktop" fill="var(--color-desktop)" />

Chart Data

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

Tailwind

<LabelList className="fill-[--color-desktop]" />

Understanding the Tooltip Component

The custom tooltip provides an enhanced user experience for exploring data points. It typically displays a label (often representing the category or x-axis value), and for each data series, its name, an indicator (dot, line, or dashed line), and the corresponding value. These elements can be selectively shown or hidden for tailored presentation.

Control the visibility of the label and indicator using the boolean hideLabel and hideIndicator props, respectively. Customize the visual style of the indicator using the indicator prop ("dot", "line", or "dashed").

If your data structure uses different keys for the tooltip's main label or series names, specify them using the labelKey and nameKey props.

Integration is straightforward: use the <ChartTooltip> component from Recharts and pass our styled <ChartTooltipContent /> component (along with any desired props) to its content prop.

import { ChartTooltip, ChartTooltipContent } from "@/components/ui/chart";

<ChartTooltip content={<ChartTooltipContent />} />

Tooltip Customization Props

Use the following props to customize the tooltip.

Tooltip Color Integration

The tooltip automatically derives the colors for its indicators and series names directly from the color values defined in your chartConfig. Ensure your config keys match the dataKey used in your chart elements (e.g., <Bar dataKey="desktop" /> corresponds to chartConfig.desktop).

Customizing Tooltip Data Keys

When your data object doesn't use the standard keys expected by the tooltip, employ the labelKey and nameKey props within <ChartTooltipContent>. This allows you to map the tooltip's display to the correct properties in your data objects.

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: "hsl(var(--chart-1))",
  },
  safari: {
    label: "Safari",
    color: "hsl(var(--chart-2))",
  },
} satisfies ChartConfig;

<ChartTooltip
  content={<ChartTooltipContent labelKey="visitors" nameKey="browser" />}
/>

In this example, setting labelKey="visitors" tells the tooltip to use the label from chartConfig.visitors ("Total Visitors") as the main title. Setting nameKey="browser" instructs it to look up the series names ("Chrome", "Safari") using the browser property from the data objects and their corresponding entries in chartConfig.

Understanding the Legend Component

Similar to the tooltip, we provide custom <ChartLegend> and <ChartLegendContent> components to render a styled legend that integrates seamlessly with your chart's theme and configuration.

import { ChartLegend, ChartLegendContent } from "@/components/ui/chart";

<ChartLegend content={<ChartLegendContent />} />

Legend Color Integration

The legend automatically picks up the appropriate colors for each series based on the color values defined in your chartConfig. The linkage happens through the dataKey of the chart elements (like <Bar> or <Line>).

Customizing Legend Data Keys

If the default keys don't match your data structure for identifying legend items, use the nameKey prop within <ChartLegendContent>. This directs the legend to use the specified property from your data objects to look up the correct label and color in the chartConfig.

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

const chartConfig = {
  chrome: {
    label: "Chrome",
    color: "hsl(var(--chart-1))",
  },
  safari: {
    label: "Safari",
    color: "hsl(var(--chart-2))",
  },
} satisfies ChartConfig;

<ChartLegend content={<ChartLegendContent nameKey="browser" />} />

Here, nameKey="browser" tells the legend to use the browser property from the data ("chrome", "safari") to find the corresponding entries in chartConfig and display their labels ("Chrome", "Safari") alongside the correct colors.

Ensuring Chart Accessibility

To enhance accessibility, Recharts provides an accessibilityLayer prop that can be added directly to chart components like <LineChart>, <BarChart>, etc.

Enabling this layer introduces keyboard navigation (allowing users to traverse data points using keys) and improves screen reader support by providing more semantic information about the chart structure and data. It's a crucial feature for creating inclusive data visualizations.

<LineChart accessibilityLayer />