shadcn/ui Chart: Recharts ile Grafik, ChartConfig, Tooltip ve Legend

Chart bileşeninin felsefesi: kompozisyon

Belge, chart bileşeninin kompozisyon düşüncesiyle tasarlandığını vurgular: grafiği Recharts bileşenleriyle kurarsınız, ChartTooltip gibi özel bileşenleri yalnızca ihtiyaç duyduğunuz yerde eklersiniz. Recharts’ın üzerine bir soyutlama katmanı konmadığı için ona kilitlenmezsiniz; yeni bir Recharts sürümü çıktığında, Recharts’ın resmî yükseltme yolunu izleyerek grafiklerinizi güncelleyebilirsiniz. Belgenin deyişiyle bileşenler sizindir.

Kaynak koda bakınca bu yaklaşımın somut hâli görülür. ChartTooltip doğrudan Recharts’ın Tooltip bileşenine, ChartLegend de Recharts’ın Legend bileşenine eşittir. shadcn’in kendi yazdığı kısımlar ChartContainer (kapsayıcı ve renk değişkenleri), ChartTooltipContent ve ChartLegendContent (içerik kutuları) ve ChartConfig tipidir.

Kurulum

CLI ile kurulum iki adımdır: bileşeni eklemek ve grafik renklerini CSS dosyanıza koymak. Elle kurulumda ayrıca recharts paketini npm ile kurar ve kaynak kodu components/ui/chart.tsx dosyasına kopyalarsınız.

npx shadcn@latest add chart

Belgede verilen renkler app/globals.css dosyasına, açık tema için :root, koyu tema için .dark seçicisi altına eklenir:

@layer base {
  :root {
    --chart-1: oklch(0.646 0.222 41.116);
    --chart-2: oklch(0.6 0.118 184.704);
    --chart-3: oklch(0.398 0.07 227.392);
    --chart-4: oklch(0.828 0.189 84.429);
    --chart-5: oklch(0.769 0.188 70.08);
  }

  .dark {
    --chart-1: oklch(0.488 0.243 264.376);
    --chart-2: oklch(0.696 0.17 162.48);
    --chart-3: oklch(0.769 0.188 70.08);
    --chart-4: oklch(0.627 0.265 303.9);
    --chart-5: oklch(0.645 0.246 16.439);
  }
}

Beş renk değişkeni, shadcn tema sisteminin bir parçasıdır. Tema değişkenlerinin genel mantığı shadcn tema ve CSS değişkenleri, koyu modun nasıl açıldığı dark mode kurulumu yazısında anlatılıyor; oklch renk biçiminin kendisi için CSS renk değerleri yazısına bakabilirsiniz.

İlk grafik: çubuk grafik

Belge ilk grafiği dört adımda kurar. Önce veri tanımlanır: altı ay boyunca masaüstü ve mobil kullanıcı sayıları. Belgedeki not önemlidir: veriniz herhangi bir biçimde olabilir, alanları grafiğe dataKey prop’uyla eşlersiniz. Ardından bir chartConfig yazılır ve grafik Recharts bileşenleriyle kurulur. components/example-chart.tsx dosyasında (ay adları Türkçeleştirildi):

"use client"

import { Bar, BarChart } from "recharts"

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

const chartData = [
  { month: "Ocak", desktop: 186, mobile: 80 },
  { month: "Şubat", desktop: 305, mobile: 200 },
  { month: "Mart", desktop: 237, mobile: 120 },
  { month: "Nisan", desktop: 73, mobile: 190 },
  { month: "Mayıs", desktop: 209, mobile: 130 },
  { month: "Haziran", desktop: 214, mobile: 140 },
]

const chartConfig = {
  desktop: {
    label: "Masaüstü",
    color: "#2563eb",
  },
  mobile: {
    label: "Mobil",
    color: "#60a5fa",
  },
} satisfies ChartConfig

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

Kodun bağlantılarını izleyelim. chartConfig içindeki desktop ve mobile anahtarları, veri nesnelerindeki alan adlarıyla aynıdır. ChartContainer bu config’e bakarak --color-desktop ve --color-mobile adında iki CSS değişkeni üretir; Bar bileşenleri de fill="var(--color-desktop)" ile bu değişkenleri kullanır. satisfies ChartConfig ifadesi, nesnenin tipe uyduğunu denetlerken anahtar adlarını korur. radius={4} çubukların köşelerini yuvarlatır, accessibilityLayer ise aşağıda anlatılan erişilebilirlik katmanını açar.

"use client" satırı resmî örnek dosyasının başında bulunur; Recharts tarayıcıda çalışan bir kütüphane olduğundan Next.js App Router’da grafik dosyanızı istemci bileşeni yapmanız gerekir.

Izgara, eksen, ipucu ve gösterge eklemek

Belge ilk grafiği dört küçük ekle adım adım zenginleştirir. Izgara için Recharts’tan CartesianGrid içe aktarılır ve vertical={false} ile yalnızca yatay çizgiler çizilir. X ekseni için XAxis eklenir: dataKey="month" etiketleri ay alanından alır, tickLine={false} ve axisLine={false} çizgileri gizler, tickMargin={10} etiketle grafik arasında boşluk bırakır, tickFormatter={(value) => value.slice(0, 3)} de ay adının ilk üç harfini gösterir.

İpucu ve gösterge ise shadcn’e ait bileşenlerle eklenir. Bu noktaya kadar yalnızca Recharts bileşenleri kullanılmıştır; belge bunların iyi görünmesinin chart bileşenindeki özelleştirmelerden geldiğini söyler. Dört adımın birleşmiş hâli:

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

import {
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
  type ChartConfig,
} from "@/components/ui/chart"

// chartData ve chartConfig yukarıdaki gibi

<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>

Burada kalıp hep aynıdır: Recharts’ın Tooltip ya da Legend bileşeni (shadcn’de ChartTooltip ve ChartLegend adıyla) yerleşimi ve davranışı üstlenir; content prop’una verilen shadcn bileşeni ise kutunun içini çizer. İpucundaki ve göstergedeki etiketler “desktop” gibi ham anahtarlar yerine config’teki label değerlerinden (“Masaüstü”, “Mobil”) gelir.

ChartConfig: etiket, ikon ve renk

Chart config, grafiğin etiketlerini, ikonlarını ve renklerini tanımladığınız yerdir. Belge bunun grafik verisinden bilinçli olarak ayrıldığını söyler: böylece aynı config’i ve renk belirteçlerini birden fazla grafik arasında paylaşabilir, verinizin ya da renklerinizin uzakta veya farklı bir biçimde tutulduğu durumlarda da bağımsız kullanabilirsiniz.

import { Monitor } from "lucide-react"

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

const chartConfig = {
  desktop: {
    label: "Masaüstü",
    icon: Monitor,
    // Tek renk: hex, hsl, oklch ya da var(--renk-adi)
    color: "#2563eb",
  },
  mobile: {
    label: "Mobil",
    // YA DA light ve dark anahtarlı bir tema nesnesi
    theme: {
      light: "#60a5fa",
      dark: "#dc2626",
    },
  },
} satisfies ChartConfig

Belgedeki örnek color ve theme alanlarını aynı anahtarda “ya da” yorumu ile gösterir. Kaynak koddaki tip tanımı bu ayrımı zorunlu kılar: bir öğe ya color taşır (theme yasak), ya da theme taşır (color yasak). İkisini aynı anahtara yazarsanız TypeScript hata verir. Bu yüzden yukarıdaki örnekte iki seçeneği iki ayrı anahtarda gösterdik.

Renkler nasıl CSS değişkenine dönüşür?

ChartContainer her grafik için benzersiz bir kimlik üretir (id prop’u verirseniz onu, vermezseniz React’in useId değerini kullanır) ve kapsayıcı div üzerine data-chart özniteliği olarak yazar. İçindeki ChartStyle parçası, config’te rengi olan her anahtar için bir --color-ANAHTAR değişkeni tanımlayan küçük bir style etiketi üretir. Kaynak koddaki tema eşlemesi açık tema için boş önek, koyu tema için .dark önekidir. Yani theme kullandığınızda, sayfanın üst öğesinde dark sınıfı varken koyu renk, yokken açık renk geçerli olur.

Değişkenler grafiğe özel [data-chart=...] seçicisine bağlandığı için aynı sayfadaki iki grafik birbirinin renklerini ezmez. Bu nedenle renkleri kullanırken her zaman var(--color-ANAHTAR) biçimini kullanırsınız. Belge üç kullanım yeri gösterir:

// 1) Bileşen prop'unda
<Bar dataKey="desktop" fill="var(--color-desktop)" />

// 2) Grafik verisinin içinde (pasta grafik gibi tek seriden çok dilimli grafiklerde)
const chartData = [
  { browser: "chrome", visitors: 275, fill: "var(--color-chrome)" },
  { browser: "safari", visitors: 200, fill: "var(--color-safari)" },
]

// 3) Tailwind sınıfı olarak
<LabelList className="fill-[--color-desktop]" />

Tema renkleriyle çalışmak

Belge, renkleri CSS değişkenleriyle vermeyi önerir; ama hex, hsl ya da oklch gibi herhangi bir renk biçimini doğrudan config’e yazmak da mümkündür. Önerilen yolda önce --chart-1, --chart-2 gibi değişkenler CSS dosyasında tanımlanır (kurulum adımındaki gibi), sonra config’te bunlara başvurulur:

const chartConfig = {
  desktop: {
    label: "Masaüstü",
    color: "var(--chart-1)",
  },
  mobile: {
    label: "Mobil",
    color: "var(--chart-2)",
  },
} satisfies ChartConfig

Bu yolun avantajı, koyu tema renklerini bir kez CSS’te tanımlamanızdır; .dark altında --chart-1 değiştiğinde config’e dokunmadan grafik de değişir. Belgenin bazı örneklerinde hâlâ hsl(var(--chart-1)) yazımı görülür. Bu, eski HSL tabanlı temalardan kalmadır: Tailwind v4 geçiş belgesi tema renkleri artık tam renk değeri olarak geldiği için config’teki hsl() sarmalayıcısını kaldırıp var(--chart-1) yazmanızı söyler. Belgedeki CSS değişkeni örneğinde .dark: { biçiminde yazılmış bir seçici de bulunur; doğru CSS seçicisi kurulum adımındaki gibi iki nokta üst üste olmadan .dark { biçimidir.

İpucu (Tooltip) ayarları

Belgeye göre bir grafik ipucu dört parçadan oluşur: etiket (label), ad (name), gösterge işareti (indicator) ve değer. Bunları açıp kapatarak ve biçimini değiştirerek ipucunu özelleştirirsiniz. Renkler config’ten otomatik olarak alınır.

Özel anahtar kullanımı en çok, her satırın ayrı bir seri olduğu verilerde gerekir. Aşağıdaki örnekte veri tarayıcı başına ziyaretçi sayısıdır. labelKey="visitors" ipucu başlığını config’teki visitors.label değerinden (“Toplam ziyaretçi”), nameKey="browser" ise satır adlarını verideki browser alanına karşılık gelen config etiketlerinden (“Chrome”, “Safari”) alır:

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

const chartConfig = {
  visitors: {
    label: "Toplam ziyaretçi",
  },
  chrome: {
    label: "Chrome",
    color: "var(--chart-1)",
  },
  safari: {
    label: "Safari",
    color: "var(--chart-2)",
  },
} satisfies ChartConfig

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

Belgedeki orijinal örnek renkleri hsl(var(--chart-1)) ile yazar; yukarıda Tailwind v4 belgesinin önerdiği var(--chart-1) biçimini kullandık. visitors anahtarının rengi yoktur; yalnızca etiket sağlamak için config’te durur ve ChartStyle rengi olmayan anahtarlar için değişken üretmez.

Gösterge (Legend) ayarları

Gösterge de aynı mantıkla çalışır: <ChartLegend content={<ChartLegendContent />} /> yazarsınız, renkler config’ten gelir. Gösterge adları için özel bir anahtar gerekiyorsa nameKey prop’u kullanılır; yukarıdaki tarayıcı verisinde <ChartLegendContent nameKey="browser" /> yazmak göstergede “Chrome” ve “Safari” adlarını gösterir.

Kaynak kodda belgede tabloyla listelenmeyen iki prop daha vardır: hideIcon (varsayılan false; config’te icon tanımlı olsa bile ikonu gizleyip renk kutusunu gösterir) ve verticalAlign (varsayılan "bottom"; kaynakta yalnızca boşluğu belirler: "top" verildiğinde gösterge kutusuna üst boşluk pt-3 yerine alt boşluk pb-3 uygulanır, böylece grafiğin üstüne konan gösterge ile çizim alanı arasında boşluk kalır).

Erişilebilirlik katmanı

Recharts grafiklerine accessibilityLayer prop’u eklendiğinde grafiğe klavye erişimi ve ekran okuyucu desteği kazandıran bir katman açılır. Belgedeki tüm çubuk grafik örneklerinde bu prop kullanılır; çizgi grafikte de <LineChart accessibilityLayer /> biçiminde yazılır. Bunu varsayılan alışkanlık hâline getirmeniz iyi olur. Erişilebilirliğin genel ilkeleri için WCAG temelleri yazısına bakabilirsiniz.

Sık yapılan hatalar

• Yükseklik vermemek. ChartContainer üzerinde min-h-[...] ya da h-[...] olmadan grafik duyarlı çalışmaz; belge bunu “önemli” notuyla vurgular.
• Config anahtarı ile var(--color-...) adının uyuşmaması. Config’te desktop varken var(--color-masaustu) yazarsanız değişken tanımsız kalır ve çubuk renksiz görünür.
• İçerik bileşenini kapsayıcı dışında kullanmak. ChartTooltipContent ve ChartLegendContent config’i useChart ile okur; kaynak koddaki bu hook kapsayıcı yoksa useChart must be used within a <ChartContainer /> mesajıyla hata fırlatır.
• config prop’unu atlamak. Belgenin giriş bölümündeki kısa örnekte <ChartContainer> config’siz yazılmıştır, ama kaynak koddaki tipte config zorunludur ve renk değişkenleri ondan üretilir.
• Aynı anahtarda hem color hem theme kullanmak. Tip bunu yasaklar; birini seçin.
• Tailwind v4’e geçip hsl(var(--chart-1)) yazmaya devam etmek. Değişkenler artık tam oklch değeri taşıdığı için belge sarmalayıcının kaldırılmasını söyler.

Sık Sorulan Sorular

shadcn/ui Chart hangi grafik kütüphanesini kullanır?

Recharts. Grafik bileşenlerini doğrudan recharts paketinden içe aktarırsınız; shadcn yalnızca kapsayıcıyı, ipucu ve gösterge içeriklerini ve config tipini sağlar.

Çizgi, alan ya da pasta grafik de çizebilir miyim?

Evet. Belge ilk grafiği çubuk grafikle anlatır ama yaklaşım Recharts bileşenlerinin hepsine uygulanır; erişilebilirlik bölümünde LineChart örneği, renk bölümünde ise dilim başına fill taşıyan veri örneği vardır. shadcn sitesinde ayrıca bir Charts kütüphanesi sayfası bulunur.

Koyu temada grafik renkleri nasıl değişir?

İki yol var: config’te var(--chart-1) gibi CSS değişkenleri kullanıp koyu değerleri .dark altında tanımlamak, ya da config’e theme: { light, dark } nesnesi yazmak. Her iki durumda da koyu mod sınıfının sayfada etkin olması gerekir.

Recharts v3 kullanabilir miyim?

Depo kopyası tarihinde belge, Recharts v3’e yükseltme çalışmasının sürdüğünü ve resmî sürümün yakında geleceğini söylüyordu; v3’ü denemek isteyenleri bir GitHub konusundaki koda yönlendiriyordu. Güncel durumu belgenin kendisinden kontrol edin.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: shadcn/ui öğrenme rehberi · Tema ve CSS değişkenleri · Dark mode kurulumu · React 19 peer dependency · Tailwind v4 geçişi · CSS değişkenleri