shadcn/ui Öğrenme Rehberi: Nasıl Çalışır, Nereden Başlanır?

shadcn/ui nasıl çalışır?

Geleneksel bir bileşen kütüphanesinde npm üzerinden bir paket kurar, bileşenleri o paketten içe aktarır ve kullanırsınız. Bileşenin görünüşünü ya da davranışını değiştirmek istediğinizde ise paketin dışından stil ezmeye, bileşeni sarmalamaya veya geçici çözümler yazmaya başlarsınız. Resmî giriş sayfası tam olarak bu sorunu hedef aldığını söyler ve kendini "bileşen kütüphanesi değil, bileşen kütüphanenizi kurma yöntemi" olarak tanımlar. Ayrıntılı felsefe için shadcn/ui nedir yazısına bakabilirsiniz.

Bu yaklaşımın pratikteki karşılığı şudur: bir bileşen eklediğinizde CLI, o bileşenin TypeScript kaynak dosyasını sizin klasörünüze yazar, bileşenin ihtiyaç duyduğu npm bağımlılıklarını kurar ve dosyadaki içe aktarma yollarını sizin projenize göre ayarlar. Örneğin Button bileşeninin kaynağı @radix-ui/react-slot ve class-variance-authority paketlerini, ayrıca projenizdeki @/lib/utils içinden cn yardımcısını kullanır. Paketler birer bağımlılık olarak güncellenebilir, ama bileşenin en üst katmanı, yani tasarım sisteminize en yakın kısım, sizin kodunuzdur.

Giriş sayfasındaki sık sorulan sorular kısmı bunu "headless" bileşen mimarisiyle açıklar: uygulamanızın çekirdeği radix-ui ya da input-otp gibi bağımlılıkları güncelleyerek düzeltmeleri alır; tasarıma yakın katman ise kütüphanenin uygulamasına bağlı değildir ve değişikliğe açık kalır. Bu yüzden "shadcn/ui sürümünü güncellemek" ifadesi, bir npm paketini yükseltmekten farklı bir anlam taşır; kopyaladığınız dosyaları kendiniz yönetirsiniz.

Sistemin dört parçası

shadcn/ui ile çalışırken sürekli karşınıza çıkacak dört yapı taşı vardır. Bunları baştan tanımak, belgeleri okurken neyin nereye ait olduğunu anlamanızı kolaylaştırır.

• shadcn CLI: shadcn adlı npm paketi. init, add, view, search, list ve build komutları belgelenmiştir. Ayrıntılar init komutu ve CLI komutları yazılarında.
• components.json: Projenizin nasıl kurulduğunu CLI'ya anlatan ayar dosyası. Stil, Tailwind CSS dosyasının yolu, temel renk, CSS değişkeni kullanımı ve içe aktarma takma adları burada durur. Yalnızca CLI kullanıyorsanız gereklidir; components.json ayarları yazısı her alanı tek tek anlatır.
• Projenize kopyalanan dosyalar: components/ui altındaki bileşenler, lib/utils.ts içindeki cn fonksiyonu ve global CSS dosyanızdaki tema değişkenleri. cn için cn fonksiyonu, değişkenler için tema ve CSS değişkenleri yazılarına bakın.
• Registry: Bileşenleri, hook'ları, sayfaları ve başka dosyaları düz JSON dosyalarıyla tanımlayıp CLI üzerinden dağıtmayı sağlayan şema. shadcn/ui'nin kendi bileşenleri de bu yolla gelir; siz de kendi registry'nizi kurabilirsiniz (kendi registry'nizi oluşturma).

Bu parçaların ilişkisi basittir: CLI, components.json dosyasını okuyarak bir registry'den bileşen tanımını çeker ve dosyaları doğru klasöre yazar. components.json yoksa ya da bileşeni belgedeki "Manual" sekmesinden elle kopyalıyorsanız CLI'ya hiç ihtiyacınız olmaz; bu yolu manuel kurulum yazısı anlatır.

İlk örnek: init, add ve içe aktarma

Belgelerin her kurulum sayfasında tekrarlanan akış üç adımdan oluşur. Önce proje klasörünüzde init komutunu çalıştırırsınız. Bu komut bağımlılıkları kurar, cn yardımcısını ekler ve proje için CSS değişkenlerini yapılandırır. Ardından ihtiyaç duyduğunuz bileşeni add ile eklersiniz.

npx shadcn@latest init
npx shadcn@latest add button

Belgeler pnpm, yarn ve bun için de eşdeğer sekmeler gösterir; burada npm ile gelen npx biçimini kullanıyoruz. add button komutundan sonra Button bileşeni projenize eklenir ve takma ad üzerinden içe aktarılır. Next.js kurulum sayfasındaki örnek, app/page.tsx dosyasında şöyledir:

import { Button } from "@/components/ui/button"

export default function Home() {
  return (
    <div>
      <Button>Kaydet</Button>
    </div>
  )
}

Buradaki @/components/ui/button yolu bir npm paketi değil, projenizdeki dosyadır. @ takma adı TypeScript yapılandırmanızdaki paths ayarıyla çözülür; Vite projelerinde ayrıca vite.config.ts içinde tanımlanır. Bu ayarların nasıl yapıldığını Vite kurulumu ve Next.js kurulumu yazıları adım adım gösterir; takma adların TypeScript tarafı ise TypeScript paths ayarları yazısında anlatılır.

Eklenen dosyayı açtığınızda karşınıza çıkan şey, bir kara kutu değil okunabilir bir React bileşenidir. Depodaki button.tsx dosyasının iskeleti aşağıdaki gibidir; varyant sınıflarının tamamını burada kısalttık:

import * as React from "react"
import { Slot } from "@radix-ui/react-slot"
import { cva, type VariantProps } from "class-variance-authority"

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

const buttonVariants = cva("inline-flex items-center ...", {
  variants: {
    variant: { default: "...", destructive: "...", outline: "...", secondary: "...", ghost: "...", link: "..." },
    size: { default: "...", sm: "...", lg: "...", icon: "...", "icon-sm": "...", "icon-lg": "..." },
  },
  defaultVariants: { variant: "default", size: "default" },
})

function Button({ className, variant = "default", size = "default", asChild = false, ...props }) {
  const Comp = asChild ? Slot : "button"
  return (
    <Comp
      data-slot="button"
      className={cn(buttonVariants({ variant, size, className }))}
      {...props}
    />
  )
}

export { Button, buttonVariants }

Bu kısa dosya, serinin birçok yazısında göreceğiniz kalıpları bir arada gösterir: cva ile tanımlanan varyantlar, cn ile birleştirilen sınıflar, asChild özelliğiyle başka bir öğeye dönüşebilme ve stil için kullanılan data-slot niteliği. Varyant değerlerinin anlamı Button varyantları yazısında, yeni varyant ekleme ise cva ile bileşen özelleştirme yazısında ele alınır.

Resmî belgeler nasıl düzenlenmiş?

ui.shadcn.com/docs adresindeki belgeler birkaç ana bölüme ayrılır ve seri de büyük ölçüde bu yapıyı izler. Hangi bilginin hangi bölümde aranacağını bilmek zaman kazandırır.

Bir bileşen sayfası genellikle aynı düzeni izler: üstte canlı bir önizleme ve kısa kullanım kodu, ardından "CLI" ve "Manual" sekmeli kurulum bölümü, sonra "Usage" başlığı altında içe aktarma ve temel kullanım, en sonda da çeşitli örnekler. Bazı sayfalarda bileşene özgü bir changelog ya da yükseltme notu bulunur. Önizlemelerde görünen kodlar depodaki examples klasöründen gelir; örneğin Button sayfasının ilk önizlemesi button-demo.tsx dosyasıdır. Serideki bileşen yazıları bu örnek dosyalarını temel alır.

Belgelerin bir parçası da changelog sayfasıdır. Ağustos 2025'te gelen shadcn CLI 3.0, Ekim 2025'te eklenen yeni bileşenler ve Aralık 2025'te duyurulan npx shadcn create gibi değişiklikler orada tarih sırasıyla anlatılır. Bu değişikliklerin özetini yenilikler ve sürüm geçmişi yazısında bulabilirsiniz.

Önce ne öğrenilmeli?

shadcn/ui'ye yeni başlıyorsanız tüm bileşenleri tek tek okumak yerine şu sırayı izlemenizi öneririz. İlk adım kavramı anlamaktır: kodun neden projeye kopyalandığını bilmeden yapılan özelleştirmeler çoğu zaman karışıklığa yol açar. İkinci adım kendi çatınıza göre kurulumdur. Üçüncü adım components.json, cn ve tema değişkenlerini kavramaktır; bunlar her bileşenin altında yatan ortak altyapıdır. Dördüncü adımda Button ve temel girdilerle pratik yaparsınız. Sonrasında form, katmanlı bileşenler, gezinme ve veri gösterimi gibi gruplara ihtiyacınıza göre geçebilirsiniz.

• Kavram: shadcn/ui nedir, ardından bu rehberdeki dört parça.
• Kurulum: init komutu ve çatınıza uygun sayfa (Vite, Next.js ya da manuel).
• Altyapı: components.json, cn(), tema değişkenleri, karanlık mod.
• İlk bileşenler: Button, Input, Field.
• Sonra ihtiyaca göre: formlar, diyaloglar, sidebar, data table, registry.

React'in kendisini, Tailwind CSS sınıflarını ya da TypeScript dilini bu seride ayrıca anlatmıyoruz. Bu konulara ihtiyaç duyarsanız React ile modern web uygulaması, Tailwind CSS rehberi ve TypeScript öğrenme rehberi yazılarına göz atabilirsiniz. Node.js ve npm kurulu değilse önce Node.js kurulumu yazısına bakın, çünkü npx komutu npm ile gelir.

Öğrenme yolları: serideki tüm yazılar

Temeller ve kurulum

• shadcn/ui nedir?: Açık kod, kompozisyon ve dağıtım ilkeleriyle shadcn/ui'nin neden klasik bir kütüphane olmadığını anlatır.
• shadcn kurulumu ve init komutu: Çatı seçimini, init komutunun seçeneklerini ve komutun projede neleri değiştirdiğini açıklar.
• Vite + React kurulumu: Vite projesinde Tailwind, tsconfig takma adları ve vite.config.ts ayarını adım adım gösterir.
• Next.js kurulumu: Next.js projesinde init akışını, rsc alanını ve "use client" yönergesini anlatır.
• Manuel kurulum: CLI kullanmadan bağımlılıkları, CSS değişkenlerini, cn yardımcısını ve components.json dosyasını elle kurmayı gösterir.
• components.json ayarları: Dosyadaki her alanın ne işe yaradığını ve hangilerinin sonradan değiştirilemeyeceğini açıklar.

CLI, tema ve proje yapısı

• CLI komutları: add, view, search: Bileşen ekleme, kurmadan önce inceleme, registry içinde arama ve registry derleme komutlarını seçenekleriyle anlatır.
• cn fonksiyonu: clsx ile tailwind-merge paketlerinin neden birlikte kullanıldığını ve bileşen stilini className ile nasıl ezeceğinizi gösterir.
• Tema ve CSS değişkenleri: background/foreground kuralını, değişken listesini, yeni renk eklemeyi ve temel renk seçeneklerini açıklar.
• Dark mode kurulumu: Next.js, Vite, Astro ve Remix projelerinde karanlık mod geçişini kurmayı anlatır.
• Tailwind v4 geçişi: Mevcut bir shadcn/ui projesini Tailwind v4 ve React 19'a yükseltirken shadcn tarafında yapılacak adımları sıralar.
• React 19 peer dependency hatası: npm ile kurulumda çıkan bağımlılık çakışmasını ve belgelerin önerdiği çözümleri açıklar.
• Monorepo kurulumu: init ile monorepo oluşturmayı, workspace'e bileşen eklemeyi ve gereken components.json ayarlarını gösterir.

Buton ve temel girdiler

• Button varyantları: variant ve size değerlerini, asChild ile link oluşturmayı ve ikonlu butonları anlatır.
• cva ile bileşen özelleştirme: Bileşen dosyasını düzenleyerek yeni varyant ve boyut eklemeyi, Slot mantığını kaynak kod üzerinden açıklar.
• Button Group ve Toggle Group: Buton gruplarını, tekli ve çoklu seçimli toggle gruplarını örneklerle gösterir.
• Input, Textarea ve Input Group: Metin girişlerini, etiket bağlamayı ve ek, buton ya da metin içeren giriş gruplarını anlatır.
• Checkbox, Radio Group, Switch, Slider: Seçim bileşenlerinin kontrollü ve kontrolsüz kullanımını ve etiketle ilişkilendirilmesini açıklar.
• Select ve Native Select: Radix tabanlı Select ile tarayıcının yerel seçim kutusunu kullanan Native Select arasındaki farkı gösterir.

Formlar

• Combobox: aranabilir select: Popover ile Command bileşenini birleştirerek aranabilir bir seçim kutusu kurmayı anlatır.
• Field bileşeni ve form düzeni: Etiket, açıklama ve hata mesajlarını tutarlı bir düzende toplayan Field ailesini açıklar.
• React Hook Form ve Zod: Controller ve Field ile doğrulamalı formlar kurmayı, eski Form bileşenini de anarak gösterir.
• TanStack Form kullanımı: useForm, form.Field ve doğrulayıcılarla form oluşturmayı anlatır.
• Next.js Server Actions ile form: Sunucu tarafı doğrulama ve bekleme durumlarıyla Server Action tabanlı formu açıklar.
• Input OTP: Doğrulama kodu girişleri için slot, grup ve ayırıcı yapısını ve maxLength kullanımını gösterir.

Tarih ve katmanlı bileşenler

• Calendar ve Date Picker: react-day-picker tabanlı takvimi ve Popover ile kurulan tarih seçiciyi anlatır.
• Dialog ve Alert Dialog: Modal pencerelerin yapısını, kontrollü açmayı ve onay diyaloglarını açıklar.
• Sheet ve Drawer: Kenardan açılan paneller ile mobil dostu çekmeceyi ve ikisinin birlikte kullanımını gösterir.
• Popover, Tooltip, Hover Card: Üç açılır katman bileşeninin farklarını ve hangisinin ne zaman uygun olduğunu anlatır.
• Dropdown Menu, Context Menu, Menubar: Menü öğelerini, onay kutulu ve radyo öğeleri, alt menüleri ve kısayol gösterimini açıklar.
• Command palette: cmdk tabanlı Command bileşeniyle klavye kısayoluyla açılan bir komut paleti kurmayı gösterir.

Gezinme ve yerleşim

• Sidebar kurulumu ve yapısı: SidebarProvider, Sidebar seçenekleri ve useSidebar ile ilk kenar çubuğunuzu kurmayı anlatır.
• Sidebar menü ve gruplar: Menü, grup, alt menü, rozet ve tetikleyici parçalarıyla kenar çubuğunun içini doldurmayı açıklar.
• Navigation Menu, Breadcrumb, Pagination: Site gezinmesi, konum izi ve sayfalama bileşenlerini örneklerle gösterir.
• Tabs, Accordion, Collapsible: İçeriği sekmelere ve açılır kapanır bölümlere ayıran bileşenleri anlatır.
• Card, Separator, Scroll Area, Resizable: Kart, ayırıcı, kaydırma alanı, yeniden boyutlanan panel ve en boy oranı bileşenlerini açıklar.
• Carousel: Embla tabanlı kaydırıcının boyut, yön, seçenek, API ve eklenti kullanımını gösterir.

Veri gösterimi ve geri bildirim

• Data table oluşturma: Table ilkelleri ve TanStack Table ile sütun tanımlarından ilk veri tablosuna kadar olan adımları anlatır.
• Data table sıralama, filtreleme, sayfalama: Tabloya sayfalama, sıralama, filtre, sütun görünürlüğü ve satır seçimi eklemeyi açıklar.
• Chart: Recharts ile grafik: ChartContainer, ChartConfig, tooltip ve legend ile tema uyumlu grafikler kurmayı gösterir.
• Sonner ile toast bildirim: Toaster ve toast() kullanımını, kullanımdan kalkan eski toast bileşeninden geçişi anlatır.
• Alert, Badge, Progress, Skeleton, Spinner: Durum, ilerleme ve yükleniyor göstergelerini bir arada açıklar.
• Item, Empty, Kbd, Avatar: Ekim 2025'te eklenen liste öğesi, boş durum ve klavye tuşu bileşenlerini Avatar ile birlikte gösterir.

Blocks, registry, MCP, sürüm ve sık hatalar

• Blocks: hazır sayfa şablonları: Hazır blokları projeye eklemeyi ve blok kütüphanesine katkı sürecini anlatır.
• Kendi registry'nizi oluşturma: registry.json ve build komutuyla kendi bileşen dağıtımınızı kurmayı açıklar.
• Namespace ve özel registry: @registry/name biçimini, kimlik doğrulamayı ve registry dizinini gösterir.
• shadcn MCP sunucusu: Yapay zekâ istemcilerinin registry'lere erişmesi için MCP sunucusunu yapılandırmayı anlatır.
• Yenilikler ve sürüm geçmişi: changelog sayfasındaki önemli değişiklikleri, npx shadcn create dahil, tarih sırasıyla özetler.
• Sık hatalar ve çözümleri: Belgelerde geçen kurulum, takma ad, bağımlılık ve registry sorunlarını çözümleriyle toplar.

Sık yapılan hatalar

• shadcn/ui'yi npm paketi gibi kurmaya çalışmak: Bileşenler bir paketten içe aktarılmaz. Doğru yol npx shadcn@latest add ile dosyayı projenize eklemek ya da belgedeki "Manual" sekmesinden kodu kopyalamaktır.
• Eklenen dosyaları dokunulmaz sanmak: components/ui altındaki dosyalar sizin kodunuzdur. Belgeler bir butonun davranışını değiştirmek için stilleri ezmek yerine doğrudan buton kodunu düzenlemenizi önerir.
• Sonradan değiştirilemeyen ayarları hafife almak: components.json içindeki style, tailwind.baseColor ve tailwind.cssVariables alanları ilk kurulumdan sonra değiştirilemez. Bu seçimleri init sırasında bilinçli yapın.
• Eski belgelerden komut kopyalamak: Belgeler Tailwind v4 ve React 19 içindir; Tailwind v3 için eski belgeler ayrı bir adreste tutulur. Eski blog yazılarındaki komutlar güncel CLI'da bulunmayabilir.
• Takma adı yapılandırmadan içe aktarmak: @/components/ui/button yolu, paths ayarı olmadan çözülmez. Kurulum sayfanızdaki tsconfig adımını atlamayın.

Sık Sorulan Sorular

shadcn/ui ücretsiz mi, lisansı nedir?

Depo ve içindeki kod MIT lisansıyla yayımlanır. Bileşen kodunu projenize kopyalayıp değiştirebilir ve ticari projelerde kullanabilirsiniz; lisansın koşulları için depodaki lisans dosyasına bakın.

shadcn/ui sadece Next.js ile mi çalışır?

Hayır. Kurulum belgesi shadcn/ui'nin tüm React çatılarıyla çalışacak biçimde tasarlandığını söyler ve Next.js, Vite, Laravel, React Router, Astro, TanStack Start, TanStack Router için ayrı rehberler ile bir manuel kurulum sayfası sunar.

Güncellemeleri nasıl alırım?

Bağımlılık olarak kurulan paketler (örneğin Radix paketleri) normal npm güncellemeleriyle yenilenir. Projenize kopyalanan bileşen dosyaları ise sizin kodunuzdur; güncel hâlini almak isterseniz bileşen sayfasındaki kodla kendi dosyanızı karşılaştırır ya da add komutunu üzerine yazma seçeneğiyle yeniden çalıştırırsınız. Üzerine yazmadan önce kendi değişikliklerinizi sürüm kontrolüne kaydedin.

TypeScript zorunlu mu?

Bileşenler TypeScript ile yazılmıştır ve belgeler TypeScript kullanmanızı önerir. Yine de components.json içinde tsx alanını false yaparak bileşenleri .jsx uzantılı JavaScript dosyaları olarak alabilirsiniz.

Aralık 2025'teki npx shadcn create nedir?

Changelog'a göre bileşen kütüphanesi (Radix ya da Base UI), ikonlar, temel renk, tema ve yazı tiplerini seçerek kendi shadcn/ui sürümünüzü oluşturmanızı sağlayan yeni bir komuttur. Ayrıntısı yenilikler yazısındadır.

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 nedir · init komutu · components.json · CLI komutları · Button varyantları · Sayfa tasarımı rehberi