shadcn/ui Nedir? Bileşen Kütüphanesi Değil, Kütüphane Kurma Yöntemi

Klasik bileşen kütüphanesi ile farkı

Alışılmış bir bileşen kütüphanesinde akış bellidir: paketi kurarsınız, bileşeni içe aktarırsınız, kullanırsınız. Sorun, bileşeni tasarım sisteminize uydurmanız ya da kütüphanede olmayan bir bileşene ihtiyaç duymanız gerektiğinde başlar. Belgeler bu durumda sık görülen üç tepkiyi sayar: kütüphane bileşenlerini başka bileşenlerle sarmak, stilleri ezmek için geçici çözümler yazmak ve API'leri birbirine uymayan farklı kütüphanelerin bileşenlerini karıştırmak.

shadcn/ui bu sorunları kodu doğrudan size vererek çözmeye çalışır. Bir butonun davranışını değiştirmek istediğinizde dış katmandan stil ezmek yerine, projenizdeki button.tsx dosyasını açıp düzenlersiniz. Aşağıdaki tablo iki yaklaşımı yan yana koyar.

İlke 1: Açık kod (Open Code)

Belgeler açık kodu üç faydayla açıklar. Birincisi şeffaflıktır: her bileşenin nasıl kurulduğunu satır satır görürsünüz. İkincisi kolay özelleştirmedir: bileşenin herhangi bir parçasını tasarım ve işlev ihtiyaçlarınıza göre değiştirebilirsiniz. Üçüncüsü yapay zekâ entegrasyonudur: kod elinizde olduğu için dil modelleri bileşenlerinizi okuyup anlayabilir ve iyileştirme önerebilir.

Açık kodla ilgili akla gelen ilk soru güncellemelerdir. Kodu kopyaladıysanız, yukarıdaki projede yapılan düzeltmeleri nasıl alırsınız? Giriş sayfasının yanıtı "headless" mimaridir. Bileşenlerin davranış çekirdeği radix-ui ya da input-otp gibi bağımlılıklarda durur ve bu paketleri güncellediğinizde düzeltmeler gelir. Tasarım sisteminize en yakın üst katman ise kütüphanenin uygulamasına bağlı değildir ve sizin değişikliklerinize açık kalır.

Depodaki bileşen dosyaları bu ayrımı açıkça gösterir. Örneğin dialog.tsx dosyası davranışı @radix-ui/react-dialog paketinden alır, görünüşü ise kendi içindeki Tailwind sınıflarıyla tanımlar:

"use client"

import * as React from "react"
import * as DialogPrimitive from "@radix-ui/react-dialog"
import { XIcon } from "lucide-react"

import { cn } from "@/lib/utils"

function Dialog({
  ...props
}: React.ComponentProps<typeof DialogPrimitive.Root>) {
  return <DialogPrimitive.Root data-slot="dialog" {...props} />
}

Buradaki DialogPrimitive.Root, diyaloğun davranışını sağlayan Radix ilkelidir; shadcn/ui bunun üzerine bir data-slot niteliği ve kendi stil sınıflarını ekler. Bu bileşenin kullanımı Dialog ve Alert Dialog yazısında anlatılıyor. Radix'in iç işleyişi bu serinin kapsamı dışındadır.

Açık kodun pratikteki anlamı

Bir örnekle somutlaştıralım. Tasarım ekibiniz tüm butonların tamamen yuvarlak köşeli olmasını istesin. Paket tabanlı bir kütüphanede bunun için tema ayarı arar ya da her kullanımda ek sınıf verirsiniz. shadcn/ui'de ise projenizdeki components/ui/button.tsx dosyasını açar, buttonVariants içindeki temel sınıf dizesinde rounded-md yerine rounded-full yazarsınız. Değişiklik, o dosyayı içe aktaran her yerde geçerli olur ve başka hiçbir yere dokunmanız gerekmez. Aşağıdaki parça, dosyadaki temel sınıf dizesinin başını kısaltarak gösterir:

const buttonVariants = cva(
  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-full text-sm font-medium ...",
  {
    // variants ve defaultVariants aynı kalır
  }
)

Bu değişikliğin bedeli de açıktır: bileşen artık sizin sürümünüzdür. İleride add button komutunu üzerine yazma seçeneğiyle yeniden çalıştırırsanız düzenlemeniz kaybolabilir; bu yüzden değişikliklerinizi sürüm kontrolünde tutmanız ve yukarıdaki kodla karşılaştırarak birleştirmeniz gerekir. Varyant eklemek gibi daha kapsamlı düzenlemeler cva ile bileşen özelleştirme yazısında anlatılıyor.

İlke 2: Kompozisyon (Composition)

shadcn/ui'deki her bileşen ortak ve birleştirilebilir bir arayüz kullanır. Belgelere göre bir bileşen sistemde yoksa onu getirip birleştirilebilir hâle getirir ve stilini sistemin geri kalanına uyacak biçimde ayarlarlar. Bunun sonucu öngörülebilirliktir: her yeni bileşen için farklı bir API öğrenmezsiniz; üçüncü taraf kaynaklı bileşenlerde bile aynı kalıplarla karşılaşırsınız.

Kompozisyonu en iyi gösteren örneklerden biri Card bileşenidir. Tek bir büyük bileşene çok sayıda özellik vermek yerine küçük parçaları iç içe yerleştirirsiniz. Belgedeki kullanım örneğini Türkçe metinlerle uyarladık:

import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"

export function SiparisKarti() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Sipariş özeti</CardTitle>
        <CardDescription>Son 30 günün siparişleri</CardDescription>
        <CardAction>Detay</CardAction>
      </CardHeader>
      <CardContent>
        <p>Toplam 42 sipariş</p>
      </CardContent>
      <CardFooter>
        <p>Güncellendi</p>
      </CardFooter>
    </Card>
  )
}

Kompozisyonu destekleyen küçük ama önemli bir ayrıntı da data-slot niteliğidir. Tailwind v4 güncellemesiyle birlikte her ilkel bileşene stil verme amacıyla bir data-slot niteliği eklendi; yukarıdaki Dialog kodunda data-slot="dialog", Button kodunda data-slot="button" olarak görünür. Bu nitelik, bir üst bileşenin içindeki belirli parçaları sınıf adı bilmeden hedeflemenizi kolaylaştırır. Nasıl kullanıldığını cn fonksiyonu ve data-slot yazısında gösteriyoruz.

Dialog, Dropdown Menu, Sidebar ve Field gibi daha karmaşık bileşenler de aynı mantığı izler: bir kök bileşen ve onun içine yerleştirilen, adları kökle başlayan alt parçalar. Bu düzen, Card ve yerleşim bileşenleri ya da Sidebar yazılarına geçtiğinizde tanıdık gelecektir.

İlke 3: Dağıtım (Distribution)

shadcn/ui aynı zamanda bir kod dağıtım sistemidir. Belgeler bunu iki parçaya ayırır: bileşenleri, bağımlılıklarını ve özelliklerini tanımlayan düz dosya yapısındaki bir şema ve bu bileşenleri projeler arasında dağıtıp kuran, farklı çatıları destekleyen bir komut satırı aracı. Şemayı kullanarak kendi bileşenlerinizi başka projelere dağıtabilir ya da yapay zekâya mevcut şemaya dayanarak yeni bileşenler ürettirebilirsiniz.

Pratikte bu, npx shadcn@latest add komutunun yalnızca shadcn/ui'nin kendi bileşenleriyle sınırlı olmadığı anlamına gelir. Komut bir bileşen adı, bir URL ya da yerel bir dosya yolu kabul eder; CLI 3.0 ile birlikte @registry/name biçiminde namespace'li registry'lerden de kurulum yapılabilir.

npx shadcn@latest add button
npx shadcn@latest add @acme/header @internal/auth-utils

İkinci satırdaki @acme ve @internal adları, components.json dosyasının registries alanında tanımlanması gereken örnek registry'lerdir. Bu konunun ayrıntısı kendi registry'nizi oluşturma ve namespace ve özel registry yazılarında.

İlke 4 ve 5: İyi varsayılanlar ve yapay zekâya hazır olma

Bileşenler özenle seçilmiş varsayılan stillerle gelir. Belgeler bunun üç sonucunu vurgular: ek iş yapmadan temiz ve sade bir görünüm elde edersiniz, bileşenler birbirine uyacak biçimde tasarlandığı için arayüzünüz tutarlı kalır ve bir şeyi değiştirmek istediğinizde varsayılanları ezmek ya da genişletmek kolaydır. Renkler, kenar yuvarlaklığı ve benzeri tasarım kararları CSS değişkenleriyle yönetilir; bunları tema ve CSS değişkenleri yazısında ele alıyoruz.

Yapay zekâya hazır olma ilkesi açık kod ve tutarlı API'nin doğal bir sonucudur. Kod projenizde durduğu ve her bileşen aynı kalıpları izlediği için bir yapay zekâ modeli bileşenlerinizin nasıl çalıştığını öğrenebilir, iyileştirme önerebilir ya da mevcut tasarımınıza uyan yeni bileşenler üretebilir. shadcn/ui bu fikri bir adım öteye taşıyarak registry'ler için bir MCP sunucusu da sunar; ayrıntısı shadcn MCP sunucusu yazısındadır.

Stiller: new-york ve Aralık 2025 sonrası

shadcn/ui'de "stil" kavramı, bileşenlerin görsel temelini (şekiller, ikonlar, animasyonlar, tipografi) ifade eder ve components.json dosyasındaki style alanında saklanır. Belgelere göre default stili kullanımdan kaldırılmıştır ve yeni projeler new-york stilini kullanır. Depo kopyasında bu stilin Tailwind v4 sürümü new-york-v4 klasöründe tutulur. Stil, kurulumdan sonra değiştirilemeyen alanlardan biridir.

Changelog'a göre Aralık 2025'te npx shadcn create duyuruldu. Bu akışta bileşen kütüphanesini (Radix ya da Base UI), ikonları, temel rengi, temayı ve yazı tiplerini seçerek kendi sürümünüzü oluşturursunuz; Vega, Nova, Maia, Lyra ve Mira adlı beş yeni görsel stil tanıtıldı. Bu yeni akışın ayrıntısını yenilikler ve sürüm geçmişi yazısında bulabilirsiniz; bu yazıdaki örnekler depodaki varsayılan Radix tabanlı new-york-v4 bileşenlerine dayanır.

Belgelerdeki diğer sayfalar: Figma, v0 ve eski belgeler

Giriş bölümünde bileşen kullanımıyla doğrudan ilgili olmayan ama bilmeniz yararlı birkaç sayfa daha vardır. Figma sayfası, bileşenlerin Figma'da yeniden çizildiği tasarım kitlerini listeler; belge bu dosyaların topluluk tarafından hazırlandığını not eder ve ücretsiz ile ücretli seçenekleri ayırır. "Open in v0" sayfası, sitedeki her bileşenin Vercel'in v0 aracında doğal dille düzenlenip projeye yapıştırılabileceğini anlatır. Legacy sayfası ise mevcut belgelerin Tailwind v4 için olduğunu, Tailwind v3 ile kullanılan sürümün belgelerinin ayrı bir adreste durduğunu belirtir. Bu üç konu serinin kapsamı dışındadır; yalnızca nereye bakacağınızı bilmeniz için anıyoruz.

JavaScript sayfası da kısa ama önemlidir: bileşenler TypeScript ile yazılmıştır ve belgeler TypeScript kullanmanızı önerir; yine de CLI, components.json içindeki tsx alanı false olduğunda bileşenleri JavaScript olarak ekler. Bu alanı components.json ayarları yazısında anlatıyoruz.

shadcn/ui ne zaman uygun, ne zaman değil?

Belgeler bir karşılaştırma ya da sıralama yapmaz; ancak ilkelerden çıkan sonuçlar açıktır. Kendi tasarım sisteminizi kurmak, bileşenlerin her satırını kontrol etmek ve kodu ekibinizle birlikte geliştirmek istiyorsanız açık kod yaklaşımı size uyar. Buna karşılık kopyalanan dosyaların bakımını üstlenirsiniz: güncellemeler bir paket yükseltmesiyle otomatik gelmez, kendi değişikliklerinizle yukarıdaki değişiklikleri siz birleştirirsiniz. Projeniz React tabanlı olmalı ve stil için Tailwind CSS kullanmalıdır, çünkü bileşenler Tailwind sınıflarıyla yazılmıştır.

Sık yapılan hatalar

• Bileşenleri bir paketten içe aktarmaya çalışmak: shadcn paketi bir CLI'dır, bileşen kütüphanesi değildir. Bileşenler @/components/ui/... gibi projenizdeki yollardan içe aktarılır.
• Kopyalanan dosyaya dokunmaktan çekinmek: Felsefenin tamamı, bu dosyaları düzenlemeniz üzerine kuruludur. Stil ezmek için dışarıdan karmaşık sınıflar eklemek yerine dosyayı değiştirin.
• Her şeyi tek seferde eklemek: İhtiyacınız olmayan onlarca bileşen dosyası bakım yükü getirir. Bileşenleri ihtiyaç doğdukça ekleyin.
• Radix ile shadcn/ui'yi karıştırmak: Davranış Radix ilkellerinden gelir, görünüm shadcn/ui dosyasındadır. Bir erişilebilirlik ya da davranış sorununu ararken hangi katmana baktığınızı bilin.
• Kullanımdan kalkan parçaları seçmek: default stili, toast bileşeni ve tailwindcss-animate belgelere göre kullanımdan kaldırılmıştır; yeni projede new-york, Sonner ve tw-animate-css kullanılır.

Sık Sorulan Sorular

shadcn/ui bir bileşen kütüphanesi değilse nedir?

Bileşen kodunu projenize dağıtan bir sistemdir: bir bileşen koleksiyonu, bu koleksiyonu tanımlayan bir şema ve onu kuran bir CLI. Sonuçta elde ettiğiniz şey, kendi projenizde yaşayan bir bileşen kütüphanesidir.

Hangi bağımlılıklar projeme girer?

Bileşene göre değişir. Button için belgenin manuel sekmesi @radix-ui/react-slot paketini ister; manuel kurulum sayfası ise ortak bağımlılıkları class-variance-authority, clsx, tailwind-merge, lucide-react ve tw-animate-css olarak listeler.

Base UI desteği var mı?

Changelog, Aralık 2025'teki npx shadcn create ile Radix ya da Base UI arasında seçim yapılabildiğini ve tüm bileşenlerin Base UI için yeniden yazıldığını söyler. Bu serideki örnekler depodaki Radix tabanlı bileşenleri kullanır.

Kaç bileşen var?

Depo kopyasında belgelerin bileşen bölümü 60 MDX sayfasından oluşur ve new-york-v4 stilinin ui klasöründe her biri için bir kaynak dosyası bulunur. Bunlara ek olarak giriş sayfaları, form rehberleri ve hazır bloklar vardır. Hepsini kurmanız gerekmez; yalnızca kullandığınız bileşenleri projenize eklersiniz.

Tasarım ekibim Figma kullanıyor, resmî bir kit var mı?

Figma sayfasındaki dosyalar topluluk katkısıdır; belge sorular için dosya sahiplerine başvurmanızı önerir. Bu kitlerin ayrıntısı bu serinin konusu değildir.

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 · init komutu · cn fonksiyonu · cva ile özelleştirme · Kendi registry'niz · React temelleri