Command
Satır içi ya da ⌘K paleti olarak eylemlerin aranabilir listesi; sayfalar, kısayollar ve vurgulanmış eşleşmeler içerir.
pnpm dlx shadcn@latest add https://hextaui.com/r/command.jsonBileşeni, HextaUI tema token'larını ve bileşenin bağımlı olduğu tüm HextaUI bileşenlerini ekler.
Henüz eklemediyseniz tema token'larını global CSS'inize ekleyin.
Bağımlılıkları yükleyin.
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cmdk cnAşağıdaki kodu kopyalayıp projenize yapıştırın.
components/ui/command.tsx components/ui/button.tsx lib/motion.ts İçe aktarma yollarını proje yapılandırmanıza uyacak şekilde güncelleyin.
Kısayol tuşları Apple cihazlarda ⌘ için, diğer her yerde Ctrl için mod kullanır. Etiketler sizin için platforma göre biçimlendirilir.
Temel
Yazmak, öğeleri siz yazdıkça filtreler ve sıralar. Eşleşmesi olmayan gruplar kaybolur ve liste yüksekliği kalanlara uyacak şekilde animasyonlanır.
Dialog
<CommandDialog /> içine bir <Command /> koyun ve useCommandHotkey ile açıp kapatın. ⌘K veya Ctrl K'ye basın. Öğe kısayolları açıkken çalışır, eşleşmeler vurgulanır ve preserveSearch sorguyu ve seçimi bir sonraki açılış için korur.
Sayfalar
page içeren bir öğe eşleşen <CommandPage /> bileşenini açar. Sayfa başlığı girdide bir chip olarak görünür, liste yandan kayarak gelir; boş aramada Backspace veya Escape geri döner.
Kaydırılabilir
Uzun listeler sınırlı bir yükseklik içinde kayar. Klavyeyle ilerlerken seçili öğe her zaman görünümde tutulur.
Asenkron sonuçlar
shouldFilter={false} ayarlayın ve çektiğiniz sonuçları render edin. <CommandLoading /> görünmeden önce 150 ms bekler, sonra en az 300 ms kalır; böylece hızlı yanıtlar asla bir spinner'ı yanıp söndürmez. İki gecikmeyi de deneyin.
Uzun içerik
Başlıklar sarar, uzun adlar seçiminize göre kısaltılır veya sarar ve kısayollar asla dışarı itilmez.
Sağdan sola
Simgeler, kısayollar, sayfa chip'i ve sayfa kayması okuma yönünü izler.
| Tuş | Action |
|---|---|
| ↓ | Sonraki öğeyi seçer. |
| ↑ | Önceki öğeyi seçer. |
| Alt↓ | Sonraki grubun ilk öğesine atlar. |
| Alt↑ | Önceki grubun ilk öğesine atlar. |
| Home | İlk öğeyi seçer. |
| End | Son öğeyi seçer. |
| CtrlN | Sonraki öğeyi seçer. Ctrl J de çalışır. vimBindings ile kapatın. |
| CtrlP | Önceki öğeyi seçer. Ctrl K de çalışır. vimBindings ile kapatın. |
| Enter | Seçili öğeyi çalıştırır. Bir bağlantı öğesinde ⌘ Enter veya Ctrl Enter onu yeni bir sekmede açar. |
| Esc | Önce aramayı temizler, sonra bir sayfa geri gider, sonra diyaloğu kapatır. |
| Backspace | Arama boşken bir sayfa geri gider. |
| ⌘P | Herhangi bir öğe kısayolu, odak komut menüsünün içindeyken öğesini çalıştırır. |
- Girdi, seçili öğeyi işaret eden bir combobox'tır; böylece ekran okuyucular ilerledikçe her öğeyi duyurur.
- Kibar (polite) bir canlı bölge, yazmayı bıraktıktan kısa süre sonra sonuç sayısını ve bir sayfayı açtığınızda veya terk ettiğinizde sayfa başlığını duyurur. İfadeyi
formatResultsverootTitleile değiştirin. <CommandDialog />gizli bir başlığa ve açıklamaya sahiptir, açıkken odağı hapseder ve kapandığında trigger'a geri verir.- Öğe kısayolları
aria-keyshortcutsile sunulur. - Azaltılmış hareket açıkken öğeler onay yanıp sönmesi olmadan çalışır ve sayfalar kaymak yerine solar.
cmdk üzerine kuruludur; <CommandDialog /> Base UI dialog üzerindedir. Parçalar, sardıkları cmdk parçasının prop'larını kabul eder.
| Prop | Tür | Varsayılan |
|---|---|---|
labelMenünün erişilebilir adı. | string | "Command menu" |
highlightHer öğedeki eşleşen harfleri vurgular ve geri kalanını soluklaştırır. | boolean | false |
shouldFilterÖğeleri kendiniz filtrelemek ve sıralamak için false yapın; örneğin sonuçlar bir sunucudan geldiğinde. | boolean | true |
filter0 (gizli) ile 1 (en iyi eşleşme) arasında bir puan döndürür. | (value: string, search: string, keywords?: string[]) => number | – |
valueSeçili öğenin değeri. | string | – |
defaultValue | string | – |
onValueChange | (value: string) => void | – |
loopListenin uçlarında başa sarın. | boolean | false |
vimBindingsCtrl N, J, P ve K ile gezinme. | boolean | true |
disablePointerSelection | boolean | false |
formatResultsYazdıktan sonra ekran okuyuculara duyurulan metin. | (count: number) => string | "3 results" |
rootTitleSon sayfadan ayrılıp köke döndüğünüzde duyurulur. | string | "All commands" |
| Öznitelik | Açıklama |
|---|---|
data-slot="command" | CSS'te kökü hedefleyin. |
data-highlighting | Vurgu açıkken ve arama boş değilken bulunur. |
--command-radius | Dış yarıçap. Öğeler ondan eş merkezli bir yarıçap türetir. |
--command-inset | Liste kenarı ile öğeleri arasındaki dolgu. |
| Prop | Tür | Varsayılan |
|---|---|---|
open | boolean | – |
defaultOpen | boolean | false |
onOpenChange | (open: boolean, details) => void | – |
preserveSearchSorgu, sayfa ve seçimin kapatmadan sonra korunması için diyaloğu bağlı (mounted) tutun. Yeniden açıldığında sorgu seçili olur. | boolean | false |
titleGörsel olarak gizli diyalog başlığı. | string | "Command menu" |
descriptionGörsel olarak gizli diyalog açıklaması. | string | "Search for a command to run." |
showCloseButton | boolean | false |
classNameDiyalog popup'ına uygulanır. | string | – |
| Öznitelik | Açıklama |
|---|---|
data-slot="command-dialog" | Diyalog popup'ı. |
data-slot="command-dialog-overlay" | Arka plan. |
data-open | Açıkken popup üzerinde bulunur. |
| Prop | Tür | Varsayılan |
|---|---|---|
valueKontrollü arama metni. | string | – |
onValueChange | (search: string) => void | – |
placeholder | string | – |
clearLabelTemizle düğmesinin erişilebilir adı. | string | "Clear search" |
backLabelSayfa chip'inin erişilebilir adı. | (title: string) => string | (title) => `Back from ${title}` |
| Öznitelik | Açıklama |
|---|---|
data-slot="command-input" | Girdi. |
data-slot="command-input-wrapper" | Simgeyi, girdiyi ve temizle düğmesini tutan satır. |
data-slot="command-clear" | Yazmaya başlayınca gösterilen temizle düğmesi. |
data-slot="command-page-chip" | Bir sayfada gösterilen geri chip'i. |
| Prop | Tür | Varsayılan |
|---|---|---|
labelListenin erişilebilir adı. | string | – |
| Öznitelik | Açıklama |
|---|---|
data-slot="command-list" | Liste. |
data-settled | Liste kendini ölçtükten sonra bulunur. Yükseklik geçişi yalnızca bu ayarlıyken çalışır. |
--cmdk-list-height | Listeyi animasyonlamak için kullanılan, görünen öğelerin yüksekliği. |
| Prop | Tür | Varsayılan |
|---|---|---|
childrenSorguyu yansıtmak için fonksiyon biçimini kullanın. | ReactNode | (search: string) => ReactNode | – |
| Öznitelik | Açıklama |
|---|---|
data-slot="command-empty" | Listede bir CommandLoading varken gizlenir. |
| Prop | Tür | Varsayılan |
|---|---|---|
loading | boolean | true |
delaySpinner gösterilmeden önce beklenecek milisaniye. | number | 150 |
minDurationSpinner göründükten sonra kalacağı asgari milisaniye. | number | 300 |
labelErişilebilir etiket. Varsayılan olarak string alt öğelerdir. | string | – |
progress | number | – |
| Öznitelik | Açıklama |
|---|---|
data-slot="command-loading" | Yükleme satırı. |
data-pending | Gecikme sırasında, satır duyurulmuş ama henüz görünür değilken bulunur. |
| Prop | Tür | Varsayılan |
|---|---|---|
heading | ReactNode | – |
valueBaşlık yoksa zorunludur. | string | – |
forceMountFiltreleme sırasında grubu görünür tutun. | boolean | false |
| Öznitelik | Açıklama |
|---|---|
data-slot="command-group" | Grup. |
[cmdk-group-heading] | Başlık öğesi. |
| Prop | Tür | Varsayılan |
|---|---|---|
onSelectTıklamada, Enter'da veya öğenin kısayolunda, onay yanıp sönmesinden sonra çalışır. | (value: string) => void | – |
valueFiltreleme için kullanılır. Varsayılan olarak, kısayol hariç öğenin metnidir. | string | – |
keywordsBu öğeyle eşleşen ek kelimeler. | string[] | – |
disabled | boolean | false |
shortcut"mod+shift+c" gibi bir kısayol tuşu. Öğe üzerinde gösterilir ve odak menüdeyken onu çalıştırır. | string | – |
pageÇalıştırmak yerine bu id'ye sahip CommandPage'i açar. | string | – |
pageTitleSayfa chip'inde gösterilen başlık. Varsayılan olarak değerdir. | string | – |
hrefÖğeyi bağlantı olarak render eder. Enter onu izler, ⌘ veya Ctrl Enter yeni bir sekme açar. | string | – |
renderBunun yerine render edilecek bir bağlantı öğesi, örneğin Next.js <Link />. | ReactElement | – |
confirmSeçimin fark edilmesi için öğeyi çalıştırmadan önce kısaca yanıp söndürün. | boolean | true |
forceMountFiltreleme sırasında öğeyi görünür tutun. | boolean | false |
| Öznitelik | Açıklama |
|---|---|
data-slot="command-item" | Öğe. |
data-selected="true" | Seçili öğede bulunur. |
data-disabled="true" | Devre dışı öğelerde bulunur. |
data-value | Filtreleme için kullanılan değer. |
data-confirming | Onay yanıp sönmesi sırasında bulunur. |
data-page | Bir sayfa açan öğelerde bulunur. |
| Prop | Tür | Varsayılan |
|---|---|---|
idOnu açan öğenin page prop'uyla eşleşir. Grupları ve öğeleri yalnızca geçerli sayfa olduğunda render edilir. | string | – |
| Prop | Tür | Varsayılan |
|---|---|---|
hotkey"mod+k" gibi bir kısayol tuşunu geçerli platform için biçimlendirir. Alt öğeler bunu geçersiz kılar. | string | – |
| Öznitelik | Açıklama |
|---|---|
data-slot="command-shortcut" | Kısayol etiketi. |
| Prop | Tür | Varsayılan |
|---|---|---|
alwaysRenderArama sırasında görünür tutun. | boolean | false |
| Öznitelik | Açıklama |
|---|---|
data-slot="command-separator" | Ayırıcı. |
| Prop | Tür | Varsayılan |
|---|---|---|
childrenVarsayılan olarak bir sayfada güncellenen tuş ipuçlarıdır. Dokunmatik ekranlarda gizlenir. | ReactNode | – |
| Öznitelik | Açıklama |
|---|---|
data-slot="command-footer" | Alt bilgi. |
| Prop | Tür | Varsayılan |
|---|---|---|
hotkeyTüm belgede dinlenir. Değiştirici tuşu olmayan kısayol tuşları, bir alana yazılırken yok sayılır. | string | – |
callback | (event: KeyboardEvent) => void | – |
options.enabled | boolean | true |
Bir yükleme göstergesinin görünür olup olmayacağını, <CommandLoading /> ile aynı gecikme ve asgari süreyle döndürür. Bir istek sürerken eski sonuçları gizlemek için kullanın.
| Prop | Tür | Varsayılan |
|---|---|---|
loading | boolean | – |
options.delay | number | 150 |
options.minDuration | number | 300 |
useCommandPages()sayfaları kendi kodunuzdan yönetmek için{ pages, page, push, pop, reset }döndürür.useCommandState(selector)arama veya filtrelenmiş sayı gibi cmdk state'ini okur.useHotkeyLabel(hotkey)bir kısayol tuşunu geçerli platform için, örneğin ⌘K veya Ctrl+K olarak biçimlendirir.
- ButtonHer varyant ve boyutta düğmeler; hızlı istekler için spinner'ı atlayan yerleşik yükleme, başarı ve hata akışı.
- HotkeyKlavye kısayollarını ayrıştırır, etiketler, duyurur ve eşleştirir; Apple platformlarında ⌘, diğer her yerde Ctrl kullanır.
- MotionHer bileşenin kullandığı yumuşatma eğrileri, süreler ve azaltılmış hareket denetimi; ayrıca boyut dönüşümleri ve kayan vurgular için hook'lar.
- SpinnerApple tarzı çentiklere ya da nefes alan bir halkaya sahip, göstermeden önce bekleyebilen ve titremesin diye yeterince uzun kalan bir yükleme göstergesi.
- Alert dialogYıkıcı ya da önemli eylemler için, asenkron işin bitmesini bekleyen ve telefonlarda alt sayfaya dönüşen bir onay iletişim kutusu.
- Context menuSağ tık ya da uzun basışla açılan eylem menüsü; alt menüler, onay kutusu ve radyo öğeleri ile dokunmatik ekranda basılı tutma geri bildirimi içerir.
Kullanıldığı bloklar
Command üzerine kurulan bloklar.