shadcn/ui Blocks rehberi: dashboard, login, sidebar ve takvim şablonları

Blok nedir, bileşenden farkı ne?

Belgelere göre bir blok tek bir bileşen olabilir (örneğin bir UI bileşeninin farklı bir çeşitlemesi) ya da birden çok bileşen, hook ve yardımcı fonksiyondan oluşan karmaşık bir yapı olabilir (örneğin bir dashboard). Teknik olarak blok, registry şemasında type değeri registry:block olan bir öğedir. Button gibi bir UI bileşeni tek dosyalık bir temel parçadır ve components/ui altına yerleşir; blok ise bu temel parçaları kullanan, çoğu zaman bir sayfa dosyasıyla birlikte gelen daha büyük bir bütündür.

Bloklar Mart 2024'te duyuruldu. Değişiklik günlüğü onları uygulamanızı kurmak için kullanabileceğiniz hazır bileşenler olarak tanımlar ve diğer shadcn/ui bileşenleriyle aynı ilkelerle yazıldıklarını, yani duyarlı (responsive), erişilebilir ve birleştirilebilir olduklarını söyler. İlk bloklar dashboard düzenleri ve kimlik doğrulama sayfalarıydı. Nisan 2024'te blok sayfasına Lift Mode eklendi: bu mod açıkken bir blok şablonunun içindeki kart, buton, form gibi küçük parçaları ayrı ayrı kopyalayabilirsiniz. Ocak 2025'te ise topluluğun blok kütüphanesine katkı vermesi için davet ve katkı belgesi yayımlandı.

Depo kopyasında hangi bloklar var?

19 Aralık 2025 tarihli depo kopyasında bloklar apps/v4/registry/new-york-v4/blocks klasöründedir ve tanımları aynı klasördeki _registry.ts dosyasında durur. Bu dosyada 64 blok tanımı bulunur. Her tanımın categories alanı bloğun blok sayfasında hangi grupta listeleneceğini belirler. Aşağıdaki tablo bu dosyadan sayılmıştır; sitede gördüğünüz liste zamanla değişebilir.

Klasörde products-01 adlı bir klasör de bulunur, ancak _registry.ts içinde tanımı yoktur; yani CLI ile kurulabilir bir öğe olarak listelenmez. Takvim bloklarının çokluğu Haziran 2025'teki takvim güncellemesinden gelir: Calendar bileşeni React DayPicker'ın son sürümüne taşınırken 30'dan fazla takvim bloğu da hazırlandı. Takvim tarafının ayrıntısı Calendar ve Date Picker yazısında, kenar çubuğu bileşeninin kendisi ise Sidebar kurulumu yazısında anlatılıyor. Sidebar belge sayfasının en üstündeki önizleme de bir bloktur: simgelere kadar daralan sidebar-07.

Bir bloğu projeye eklemek

Blok eklemek için önce projenizde components.json dosyası olmalıdır; yoksa init komutuyla oluşturursunuz. Ardından bloğun adını add komutuna verirsiniz:

npx shadcn@latest add login-01

Belgelerdeki diğer komutlarda olduğu gibi pnpm, yarn veya bun kullanıyorsanız aynı komutu kendi paket yöneticinizin çalıştırıcısıyla yazabilirsiniz. CLI'nin ne yapacağını anlamak için bloğun registry tanımına bakmak yeterlidir. _registry.ts dosyasında login-01 şöyle tanımlanmıştır:

{
  name: "login-01",
  description: "A simple login form.",
  type: "registry:block",
  registryDependencies: ["button", "card", "input", "label", "field"],
  files: [
    {
      path: "blocks/login-01/page.tsx",
      target: "app/login/page.tsx",
      type: "registry:page",
    },
    {
      path: "blocks/login-01/components/login-form.tsx",
      type: "registry:component",
    },
  ],
  categories: ["authentication", "login"],
}

Bu tanımdan üç şey çıkar. Birincisi, registryDependencies listesindeki beş bileşen (button, card, input, label, field) projenizde yoksa önce onlar eklenir. İkincisi, registry:page türündeki dosya target alanında yazan app/login/page.tsx yoluna yazılır. Registry şeması target alanını sayfa ve genel dosya türleri için zorunlu tutar, çünkü bir sayfanın nereye gideceği components.json takma adlarından çıkarılamaz. Üçüncüsü, registry:component türündeki login-form.tsx için hedef yazılmamıştır; CLI onu components.json içindeki aliases.components ayarına göre bileşen klasörünüze koyar.

Depodaki sayfa dosyası şöyledir. İçe aktarma yolunun @/registry/new-york-v4/... ile başladığına dikkat edin; bu yol deponun kendi iç düzenidir:

import { LoginForm } from "@/registry/new-york-v4/blocks/login-01/components/login-form"

export default function Page() {
  return (
    <div className="flex min-h-svh w-full items-center justify-center p-6 md:p-10">
      <div className="w-full max-w-sm">
        <LoginForm />
      </div>
    </div>
  )
}

Bloklar projenize kopyalanırken CLI içe aktarmaları sizin takma adlarınıza göre çözer. Değişiklik günlüğündeki Mart 2025 (shadcn 2.5.0) notu bunu anlatır: kurulum sırasında eklenen tüm dosyalar izlenir ve içe aktarmalar ile takma adlar birkaç geçişte doğru biçimde çözülür. Dosyalar kopyalandıktan sonra bunlar artık sıradan React bileşenleridir. LoginForm içindeki İngilizce metinleri Türkçeleştirmek, alanları kendi formunuza göre değiştirmek ya da form doğrulaması eklemek tamamen size kalmıştır. Form tarafında Field bileşeni ve React Hook Form ile doğrulama yazıları işinize yarar.

init komutu da bileşen adı kabul eder. Ağustos 2024 değişiklik günlüğü, yeni bir projeyi kurarken blokları da aynı anda ekleyen şu örneği verir:

npx shadcn init sidebar-01 login-01

Büyük bir blok: dashboard-01 neler getirir?

Blokların ne kadar büyüyebileceğini görmek için dashboard-01 tanımına bakmak öğreticidir. Açıklaması kenar çubuğu, grafikler ve veri tablosu olan bir dashboard olarak yazılmıştır. dependencies alanında yedi npm paketi vardır: @dnd-kit/core, @dnd-kit/modifiers, @dnd-kit/sortable, @dnd-kit/utilities, @tabler/icons-react, @tanstack/react-table ve zod. registryDependencies alanında ise sidebar, breadcrumb, chart, table, drawer, sheet, sonner dahil 19 shadcn/ui bileşeni sayılır.

Dosya listesinde sayfanın yanında registry:file türünde bir data.json bulunur ve hedefi app/dashboard/data.json olarak verilmiştir. Bu dosya tablodaki örnek verileri taşır; gerçek uygulamada onu kendi veri kaynağınızla değiştirmeniz beklenir. Geri kalan dosyalar app-sidebar, chart-area-interactive, data-table, nav-main, nav-user, section-cards, site-header gibi bileşenlerdir. Bu blok, data table, chart ve sidebar menüsü yazılarında ayrı ayrı anlatılan parçaların bir arada nasıl kullanıldığını gösteren iyi bir başvuru örneğidir.

Next.js dışında ve monorepo içinde bloklar

Blok tanımlarındaki hedefler app/login/page.tsx gibi Next.js App Router yollarıdır. Mart 2025 değişiklik günlüğüne göre CLI çatıyı (framework) otomatik algılar ve yolları buna uyarlar; notta Laravel, Vite ve React Router da anılır. Yine de dosya tabanlı yönlendirme kullanmayan bir Vite projesinde sayfa dosyasının yönlendiricinize nasıl bağlanacağını sizin belirlemeniz gerekir. Vite kurulumu için Vite ile shadcn/ui, Next.js için Next.js kurulumu yazılarına bakın.

Monorepo belgesi blokların çalışma alanları arasında nasıl bölündüğünü açıkça örnekler: apps/web içinde npx shadcn@latest add login-01 çalıştırdığınızda CLI button, label, input ve card bileşenlerini packages/ui altına, login-form bileşenini ise apps/web/components altına kurar. Temel bileşenler paylaşılan pakete, bloğa özgü bileşen uygulamaya gider. Ayrıntılar monorepo kurulumu yazısında.

Yeni stillerde blok kısıtlaması

Aralık 2025'te gelen npx shadcn create ile kurulan projeler farklı görsel stiller kullanabilir (bkz. yenilikler yazısı). CLI 3.6.2 kaynak kodundaki add komutu, stil adı base- veya radix- ile başlayan projelerde adı sidebar-, login-, signup-, otp- ya da calendar- ile başlayan öğeleri kurmaz. Bu durumda kaynak koddaki şu iki uyarı metni basılır: The ... component(s) are not available for the ... style yet. They are coming soon. ve In the meantime, you can visit the blocks page on https://ui.shadcn.com/blocks and copy the code. Yani depo kopyası tarihinde bu bloklar yalnızca klasik new-york düzeninde CLI ile kurulabiliyordu; yeni stillerde kodu blok sayfasından kopyalamanız öneriliyordu.

Blok kütüphanesine katkı vermek

Blocks belge sayfası aslında bir katkı rehberidir. Akış dört aşamadan oluşur: çalışma ortamını hazırlamak, bloğu yazmak, onu registry tanımına eklemek ve pull request açmak. Ortamı hazırlamak için depoyu klonlayıp yeni bir dal açar, bağımlılıkları kurar ve geliştirme sunucusunu başlatırsınız:

git clone https://github.com/shadcn-ui/ui.git
git checkout -b username/my-new-block
pnpm install
pnpm www:dev

Belge, bloğun kebab-case adlı bir klasöre konmasını ve tek dosyayla başlayıp sonra dosya eklenebileceğini söyler. Sayfa, bileşen, hook ve yardımcı dosya içeren örnek yapı şöyledir:

dashboard-01
└── page.tsx
└── components
    └── hello-world.tsx
    └── example-card.tsx
└── hooks
    └── use-hello-world.ts
└── lib
    └── format-date.ts

Sonra blok, registry öğesi şemasına uyan bir tanımla blok listesine eklenir. Belgedeki örnek tanımın kısaltılmış hali:

export const blocks = [
  // ...
  {
    name: "dashboard-01",
    author: "shadcn (https://ui.shadcn.com)",
    title: "Dashboard",
    description: "A simple dashboard with a hello world component.",
    type: "registry:block",
    registryDependencies: ["input", "button", "card"],
    dependencies: ["zod"],
    files: [
      {
        path: "blocks/dashboard-01/page.tsx",
        type: "registry:page",
        target: "app/dashboard/page.tsx",
      },
      {
        path: "blocks/dashboard-01/components/hello-world.tsx",
        type: "registry:component",
      },
      {
        path: "blocks/dashboard-01/hooks/use-hello-world.ts",
        type: "registry:hook",
      },
      {
        path: "blocks/dashboard-01/lib/format-date.ts",
        type: "registry:lib",
      },
    ],
    categories: ["dashboard"],
  },
]

Tanım değiştiğinde pnpm registry:build çalıştırılır; belge her dosya değişikliğinde değil, yalnızca tanım güncellendiğinde gerektiğini not eder. Blok yerelde http://localhost:3333/blocks/[CATEGORY] adresinde, tam ekran önizleme ise /view/styles/new-york/dashboard-01 biçimindeki bir adreste görülür. Yayına hazır olduğunuzda build betiğini yeniden çalıştırır, pnpm registry:capture ile ekran görüntüsü alır ve pull request açarsınız. İnceleme ve birleştirme sonrasında blok sitede yayınlanır ve CLI ile kurulabilir hale gelir.

Belgedeki kurallar kısaca şunlardır: name, description, type, files ve categories zorunludur; kullanılan tüm registry bileşenleri registryDependencies içinde, tüm npm paketleri dependencies içinde listelenmelidir; bloğun bir sayfası varsa files dizisinin ilk öğesi olmalı ve target taşımalıdır (CLI'nin dosya tabanlı yönlendirmede sayfayı doğru yere koyması için); içe aktarmalar her zaman @/registry yolunu kullanmalıdır. Yeni bir kategori gerekiyorsa registryCategories dizisine name, slug ve hidden alanlarıyla eklenir.

Bloklar ve v0

Mart 2024 duyurusunda bir v0 hesabınız varsa bloğu Edit in v0 ile v0'da açıp istemlerle değiştirmeye devam edebileceğiniz belirtilir. v0 belge sayfası ui.shadcn.com üzerindeki her bileşenin v0'da düzenlenebildiğini söyler. Kendi registry'nizi yayımlıyorsanız https://v0.dev/chat/api/open?url=[URL] uç noktasıyla bir öğeyi v0'da açtırabilirsiniz. Belgedeki buton örneğinin sadeleştirilmiş hali (orijinalde v0 logosu SVG olarak eklenir):

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

export function OpenInV0Button({ url }: { url: string }) {
  return (
    <Button aria-label="Open in v0" asChild>
      <a
        href={`https://v0.dev/chat/api/open?url=${url}`}
        target="_blank"
        rel="noreferrer"
      >
        v0'da aç
      </a>
    </Button>
  )
}

Belge bu özelliğin cssVars, css, envVars, namespace'li registry'leri ve gelişmiş kimlik doğrulama yöntemlerini desteklemediğini vurgular; yalnızca token sorgu parametresiyle kimlik doğrulama çalışır. v0 ürününün kendi ayrıntıları bu yazının kapsamı dışındadır.

Sık yapılan hatalar

• Bloğu bir paket gibi güncellemeyi beklemek: Blok kodu projenize kopyalanır. Kaynakta düzeltme çıksa bile sizin dosyalarınız kendiliğinden değişmez; yeniden eklemek değişikliklerinizin üzerine yazabilir.
• Hedef dosyanın varlığını kontrol etmemek: login-01 ve benzerleri app/login/page.tsx gibi sabit yollara yazar. Aynı yolda kendi sayfanız varsa önce yedekleyin ya da commit edin.
• Örnek veriyi gerçek veri sanmak: dashboard-01 ile gelen data.json yalnızca gösterim içindir.
• Bağımlılık yükünü hesaba katmamak: Büyük bloklar onlarca bileşen ve birkaç npm paketi getirir. Yalnızca bir parçaya ihtiyacınız varsa blok sayfasındaki Lift Mode ile o parçayı almak daha temizdir.
• Katkıda sayfayı listenin sonuna koymak: Kurallara göre sayfa files dizisinin ilk öğesi olmalı ve target taşımalıdır.

Sık Sorulan Sorular

Bloklar ücretli mi, lisansı nedir?

Değişiklik günlüğüne göre bloklar açık kaynaktır ve kaynakları GitHub'dadır. Depo MIT lisanslıdır; bloğu projenizde kullanabilir, değiştirebilir ve geri katkı verebilirsiniz.

Aynı anda birden fazla blok kurabilir miyim?

Evet. add komutu birden fazla ad kabul eder; init da kurulum sırasında blok adları alabilir. İki blok aynı hedef yola dosya yazıyorsa (örneğin iki farklı login bloğu), namespace belgesindeki çözümleme kuralına göre aynı hedefteki dosyalardan en son çözümlenen geçerli olur.

Bloğu eklemeden önce içeriğini görebilir miyim?

Evet. view komutu bir registry öğesinin dosyalarını ve bağımlılıklarını kurmadan önce gösterir: npx shadcn@latest view login-01.

Kendi bloklarımı başka projelere nasıl dağıtırım?

shadcn deposuna katkı vermek zorunda değilsiniz. Aynı şemayla kendi registry.json dosyanızı yazıp shadcn build ile yayımlayabilirsiniz; ayrıntılar registry kurma yazısında.

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 · Kendi registry'nizi kurun · Sidebar kurulumu · Calendar ve Date Picker · CLI komutları