shadcn/ui Base UI’a geçti. İşte kodunuzda gerçekten değişenler

Tek paragrafta ne değişti

Yeni shadcn/ui projeleri Base UI primitive’leri alıyor. Radix hâlâ tam destekleniyor. shadcn ekibi, bir bileşen yalnızca Base UI’da bulunmadıkça her güncellemenin ve yeni bileşenin iki kütüphane için de yayınlanacağını söyledi. Mevcut projelere dokunulmuyor. Taze bir projede Radix istiyorsanız tek bir bayrak geçersiniz:

npx shadcn@latest init -b radix

init komutunu etkileşimsiz çağıran ve Radix bekleyen CI’ınız ya da betikleriniz varsa, taze bir checkout sizi şaşırtmadan önce o bayrağı şimdi ekleyin.

Varsayılan neden değişti

İki gerekçe verildi. Base UI, haftada altı milyonun üzerinde indirmeyle kararlı 1.6.0 sürümüne ulaşmıştı ve shadcn/create ile oluşturulan projeler zaten yaklaşık ikiye bir oranla Radix yerine Base UI seçiyordu. Varsayılan, insanların seçtiğini izledi.

Base UI, Radix, Material UI ve Floating UI’ın arkasındaki kişiler tarafından yapılıyor ve soy belli oluyor. Radix’in hiç yayınlamadığı Combobox, Autocomplete, Number Field, Toast ve Preview Card gibi primitive’leri kapsıyor. Eylül 2026 itibarıyla 1.8.0 sürümünde.

Mevcut bir uygulamayı taşımalı mısınız?

Muhtemelen bu çeyrekte değil ve hepsini bir anda değil.

Uygulama kararlıysa, eksik bir primitive’e takılmıyorsanız ve ekipte kimsenin belirli bir şikâyeti yoksa Radix’te kalın. Bağımlı olduğunuz hiçbir şey ortadan kalkmıyor.

İkinci bir kütüphaneye uzanmadan Combobox ya da Number Field’a ihtiyacınız varsa, bileşenleri zaten Tailwind v4 için yeniden yazıyorsanız ya da yeni shadcn/ui bileşenlerinin önce hedeflediği katmanda olmak istiyorsanız geçin.

Her iki durumda da karar vermeden önce bir sonraki bölümü okuyun, çünkü farklar kozmetik değil.

Gerçekten karşılaşacağınız her API farkı

Bunları nasıl başarısız olduklarına göre grupladım. İlk grup build’inizi bozar. İkinci grup sorunsuz derlenir ve davranışı sessizce değiştirir, ki bu daha kötü.

Build’i bozan değişiklikler

asChild, render olur. Herkesin ilk karşılaştığı değişiklik bu.

// Radix
<DialogTrigger asChild>
  <Button>Open</Button>
</DialogTrigger>

// Base UI
<DialogTrigger render={<Button />}>Open</DialogTrigger>

render prop’u bir eleman ya da bir fonksiyon alır. Fonksiyon biçimi size durumu verir; bu, açıkken simgesi değişen bir tetikleyici gibi şeyler için kullanışlıdır.

Sabitlenmiş açılır öğeler bir Positioner kazanır. Menu, Select, Popover ve Tooltip Portal > Content yapısından Portal > Positioner > Popup yapısına geçer. Dialog’da Positioner yoktur; Backdrop ve Popup kullanır.

Overlay artık Backdrop. Yeniden adlandırın ve devam edin.

Select değerleri null olabilir. Kontrollü bir Select string değil Value | null tutar. useState<string>("") ifadeniz useState<string | null>(null) olur ve değeri string olarak okuyan her yere bir koruma gerekir.

Accordion ve Toggle Group değerleri her zaman dizidir. Tekli modda bile value="a", value={["a"]} olur. Tabs tek bir değer tutmaya devam eder.

onOpenChange ikinci bir argüman alır. Radix, kapanmayı durdurmak için event.preventDefault() çağırmanıza izin verir. Base UI (open, details) geçirir ve siz details.cancel() çağırırsınız. details.reason alanı Escape tuşu mu, dışarı tıklama mı yoksa başka bir şey mi olduğunu söyler; "kaydedilmemiş değişiklikler" diyalogları için kullanışlı.

Açık durum seçicileri değişir. data-[state=open]: varyantları data-open: olur. Bu, className string’lerinizde ve cva varyantlarınızda saklanır; dolayısıyla geçişi bitti ilan etmeden önce data-[state= için grep yapın.

Sessiz davranış değişiklikleri

Tabs varsayılan olarak elle etkinleşir. Radix’te ok tuşları odağı taşır ve sekmeyi etkinleştirir. Base UI’da ok tuşları odağı taşır, etkinleştirmek için Enter ya da Space’e basarsınız. Testleriniz ya da kullanıcılarınız Radix davranışını bekliyorsa listede activateOnFocus ayarlayın.

Checkbox ve radio menü öğeleri menüyü açık tutar. closeOnClick, CheckboxItem ve RadioItem için varsayılan olarak false. Düz öğeler kapatmaya devam eder. Bu tartışmasız daha iyi bir varsayılan, ama kullanıcılarınızın fark edeceği bir değişiklik.

Gezinme menüleri daha hızlı açılır. Base UI’ın hover delay değeri varsayılan olarak 50ms. Radix’in delayDuration değeri varsayılan olarak 200ms idi. Hızlı menüler, biri fareyi başlığın üzerinden geçirip üç panel art arda açılana kadar harika hissettirir. Ayarlayın.

Canınızı yakmayan bir geçiş sırası

İki kütüphaneyi de kurulu tutun. Her commit’te bir bileşen taşıyın. Aralarda testlerinizi çalıştırın. Şu sırayla:

1. Açılır öğesi olmayan yaprak bileşenler: Switch, Checkbox, Slider, Toggle, Progress. Çoğunlukla yeniden adlandırma işi.
2. Tabs ve Accordion. Dizi değerlerini düzeltin ve activateOnFocus konusunda karar verin.
3. Dialog ve Alert Dialog. Backdrop ve Popup yapısını ve details.cancel() desenini, işleri karıştıracak Positioner’ın olmadığı burada öğrenin.
4. Popover ve Tooltip. Positioner ekleyin.
5. Select, Combobox, Dropdown Menu, Context Menu. Null olabilen değerler, closeOnClick ve tüm açılır öğe ağacı. Bunları en sona, en çok testle bırakın.

Bir bileşeni Base UI sürümüyle değiştirmek tek bir CLI komutu ve kaynağınız git’te; dolayısıyla ona güvenmek yerine diff’i inceleyin:

npx shadcn@latest add dialog --overwrite

Sonra git diff components/ui/dialog.tsx çalıştırın ve tutmadan önce her satırı okuyun.

Yapmayacağım şeyler

Tüm ağaçta bir codemod çalıştırıp umut etmezdim. Build’i bozan değişiklikleri bulmak kolay. Sessiz olanları bulmak değil ve bir codemod, ayarlar sayfanızın artık sekme değiştirmek için iki tuş vuruşu gerektirdiğini size söyleyemez.

Primitive katmanını değiştirip bileşenleri aynı PR’da yeniden tasarlamazdım da. shadcn/ui’ın amacı kodun size ait olması. Sahip olmak, diff’i okumak demektir.

Geçişin sizin yerinize yapılmasını istiyorsanız

HextaUI, bir shadcn/ui projesine eklediğiniz bir registry’dir. Her bileşen zaten Base UI üzerine yazılmıştır, shadcn/ui adlarını ve prop’larını korur ve aynı tema token’larını kullanır; dolayısıyla npx shadcn@latest add https://hextaui.com/r/dialog.json --overwrite komutu diğer dosyalarınızın yanına, components/ui içine bir Base UI Dialog’u yerleştirir. Bileşenler MIT ve ücretsizdir. HextaUI vs shadcn/ui sayfası nelerin farklı olduğunu ve düz shadcn/ui’ın ne zaman daha iyi seçim olduğunu listeler.

SSS

Radix kullanımdan kalktı mı? Hayır. shadcn/ui her bileşeni iki kütüphane için de yayınlıyor ve ekip üretimde hâlâ Radix çalıştırıyor.

Radix ve Base UI bileşenlerini tek projede karıştırabilir miyim? Evet. Geçiş yaparken iki bağımlılığı birden taşırsınız. Pek çok proje uzun süre karışık kalacak ve bunda sorun yok.

Tema token’larımı değiştirmem gerekir mi? Hayır. --background, --primary, --radius ve diğerleri değişmedi. Primitive katmanı Tailwind tarafından bağımsızdır.

Base UI React Server Components destekliyor mu? Base UI primitive’leri, Radix gibi istemci bileşenleridir. "use client" yönergesini shadcn/ui nereye koyuyorsa orada tutun.

Resmî değişiklik günlüğü nerede? Temmuz 2026 girdisi ui.shadcn.com/docs/changelog/2026-07-base-ui-default adresinde.