Command

Gruplu, aranabilir ve klavyeyle gezilen bir komut listesi. Sayfa içinde kullanabilir ya da Command.Dialog ile ⌘K komut paleti olarak açabilirsin.

BetaKaynak kod

Sonuç bulunamadı.

Son komut: henüz yok

import { Command } from "@meridui/react";

export function Example() {
  return (
    <Command.Root
      onSelect={(value) => run(value)}
      label="Komut menüsü"
      resultsLabel={(count) => `${count} sonuç`}
    >
      <Command.Input placeholder="Bir komut yaz ya da ara…" />
      <Command.List label="Öneriler">
        <Command.Empty>Sonuç bulunamadı.</Command.Empty>
        <Command.Group heading="Sayfalar">
          <Command.Item value="Ana sayfa" keywords={["dashboard", "pano"]}>Ana sayfa</Command.Item>
          <Command.Item>Projeler</Command.Item>
          <Command.Item>Ayarlar</Command.Item>
        </Command.Group>
        <Command.Separator />
        <Command.Group heading="Aksiyonlar">
          <Command.Item value="Yeni proje" shortcut={["mod", "shift", "p"]}>Yeni proje</Command.Item>
          <Command.Item value="Üye davet et" shortcut={["mod", "shift", "i"]}>Üye davet et</Command.Item>
          <Command.Item disabled>Çalışma alanını sil</Command.Item>
        </Command.Group>
      </Command.List>
    </Command.Root>
  );
}

Import

import { Command } from "@meridui/react";

Anatomi

<Command.Root>
  <Command.Input />
  <Command.List>
    <Command.Empty />
    <Command.Group heading="…">
      <Command.Item />
    </Command.Group>
    <Command.Separator />
  </Command.List>
</Command.Root>

<Command.Dialog>{/* aynı parçalar */}</Command.Dialog>

Root arama metnini ve aktif öğeyi tutar, öğeleri filtreler ve tuşları yönetir.
Input arama kutusudur (role="combobox"). Focus hep onda kalır; aktif öğe aria-activedescendant ile bildirilir.
List sonuçların role="listbox" elemanıdır. Item bir seçenektir; Group bir başlık ekler.
Empty yalnızca hiçbir öğe eşleşmediğinde render'lanır. Separator arama yazılırken gizlenir.
Dialog hepsini ⌘K / Ctrl+K ile açılan modal bir Dialog içine koyar.

Command.Dialog global bir kısayol kaydeder (varsayılan ["mod", "k"]; kapatmak için shortcut={null} ver), açılınca input'a focus verir ve bir öğe seçilince kapanır (closeOnSelect). Bu site ⌘K'yı kendi araması için kullandığından örnek ⌘J kullanıyor.

Son komut: henüz yok

const [open, setOpen] = useState(false);

<Button variant="secondary" onClick={() => setOpen(true)}>
  Komut menüsünü aç <Shortcut keys={["mod", "j"]} size="sm" />
</Button>

{/* shortcut varsayılan olarak ⌘K / Ctrl+K; bu site onu arama için kullanıyor. */}
<Command.Dialog
  open={open}
  onOpenChange={setOpen}
  onSelect={(value) => run(value)}
  shortcut={["mod", "j"]}
  label="Komut menüsü"
>
  <Command.Input placeholder="Sayfa ve aksiyon ara…" />
  <Command.List label="Öneriler">
    <Command.Empty>Bu aramayla eşleşen bir şey yok.</Command.Empty>
    <Command.Group heading="Sayfalar">
      <Command.Item value="Ana sayfa">Ana sayfa</Command.Item>
      <Command.Item value="Faturalandırma">Faturalandırma</Command.Item>
      <Command.Item value="Ekip">Ekip</Command.Item>
    </Command.Group>
    <Command.Group heading="Tema">
      <Command.Item value="Açık tema">Açık</Command.Item>
      <Command.Item value="Koyu tema">Koyu</Command.Item>
    </Command.Group>
  </Command.List>
</Command.Dialog>

Filtreleme

Varsayılan olarak aramadaki her kelime öğenin value'sunda ya da keywords'ünde geçmelidir; büyük/küçük harf ve aksanlar yok sayılır ("cafe", "Café"yi bulur). Farklı eşleştirmek için filter ver; filtrelemeyi sunucuda yapıp yalnızca eşleşen öğeleri render'lıyorsan shouldFilter={false} kullan.

<Command.Root filter={(value, search) => value.toLowerCase().startsWith(search.toLowerCase())}>

Öğe kısayolları

shortcut, tuşları Shortcut ile gösterir; komut menüsünde focus varken bu tuşlara basmak öğeyi çalıştırır. Yazmanın engellenmemesi için kısayollarda bir değiştirici tuş (⌘, Ctrl ya da Alt) gerekir.

API referansı

Root

onSelect dışındaki tüm <div> attribute'larını kabul eder.

Prop	Tip	Varsayılan	Açıklama
`search`	`string`	–	Controlled arama metni.
`defaultSearch`	`string`	`""`	Uncontrolled kullanımda başlangıç arama metni.
`onSearchChange`	`(search: string) => void`	–	Arama metni değişince çağrılır.
`filter`	`(value, search, keywords) => boolean`	–	Özel eşleştirme fonksiyonu. Varsayılanı büyük/küçük harf ve aksan duyarsız kelime eşleştirmesi.
`shouldFilter`	`boolean`	`true`	Öğeleri kendin filtrelemek için false ver.
`loop`	`boolean`	`true`	Ok tuşlarıyla sondan başa döner.
`onSelect`	`(value: string) => void`	–	Seçilen her öğenin değeriyle, öğenin kendi onSelect'inden sonra çağrılır.
`label`	`string`	`"Command menu"`	Arama kutusunun erişilebilir adı.
`resultsLabel`	`(count: number) => string`	`"N results"`	Arama sırasında ekran okuyuculara bildirilen durum metni.
`shortcutLabels`	`ShortcutKeyLabels`	–	Öğe kısayolları için okunan tuş adları; İngilizce varsayılanlarla birleştirilir.
`ref`	`Ref<HTMLDivElement>`	–	Root elemanına iletilen ref.

Input

value, defaultValue, onChange ve type dışındaki tüm <input> attribute'larını kabul eder; arama metni Root'ta tutulur.

Prop	Tip	Varsayılan	Açıklama
`placeholder`	`string`	`"Type a command or search…"`	Placeholder metni.
`onValueChange`	`(search: string) => void`	–	Yeni arama metniyle çağrılır.
`ref`	`Ref<HTMLInputElement>`	–	Input'a iletilen ref.

List, Empty, Group, Separator

Prop	Tip	Varsayılan	Açıklama
`List label`	`string`	`"Suggestions"`	Listbox'ın erişilebilir adı.
`Empty children`	`ReactNode`	`"No results found."`	Hiçbir öğe eşleşmediğinde gösterilir.
`Group heading`	`ReactNode`	–	Görünür başlık; grubun adı da olur.
`Separator alwaysRender`	`boolean`	`false`	Arama yazılırken de separator'ı gösterir.

Item

onSelect dışındaki tüm <div> attribute'larını kabul eder.

Prop	Tip	Varsayılan	Açıklama
`value`	`string`	–	Filtreleme ve onSelect için benzersiz değer. Children string ise varsayılanı o metindir.
`keywords`	`string[]`	–	Eşleşen ek arama terimleri.
`onSelect`	`(value: string) => void`	–	Öğe tıklama, Enter ya da kısayoluyla seçildiğinde çağrılır.
`disabled`	`boolean`	`false`	Ok tuşları atlar, tıklamalar yok sayılır.
`leading`	`ReactNode`	–	Etiketten önce gösterilen ikon.
`shortcut`	`string[]`	–	Etiketten sonra gösterilen tuşlar, örneğin ["mod", "s"]; öğeyi de çalıştırır.
`ref`	`Ref<HTMLDivElement>`	–	Seçeneğe iletilen ref.

Dialog

Root'un tüm prop'larını ve şunları alır:

Prop	Tip	Varsayılan	Açıklama
`open`	`boolean`	–	Controlled açık/kapalı state'i.
`defaultOpen`	`boolean`	`false`	Uncontrolled kullanımda başlangıç state'i.
`onOpenChange`	`(open: boolean) => void`	–	Açık/kapalı state'i değişmesi gerektiğinde çağrılır.
`shortcut`	`string[] \| null`	`["mod", "k"]`	Dialog'u açıp kapatan global tuş kombinasyonu; null verirsen kapanır.
`closeOnSelect`	`boolean`	`true`	Bir öğe seçilince dialog'u kapatır.
`container`	`Element \| null`	`document.body`	Portal hedefi.

Stil verme

Sınıf	Eleman
`.mrd-command`	Root
`.mrd-command__input-wrap`, `.mrd-command__input`	Arama satırı ve input
`.mrd-command__list`	List
`.mrd-command__group`, `.mrd-command__heading`	Group ve başlığı
`.mrd-command__item`	Item
`.mrd-command__leading`, `.mrd-command__label`, `.mrd-command__shortcut`	Item parçaları
`.mrd-command__empty`, `.mrd-command__separator`	Empty ve Separator
`.mrd-command-dialog`	Dialog yüzeyi

Attribute	Nerede	Değerler
`data-active`	Item	aktif öğede bulunur
`data-disabled`	Item	devre dışıyken bulunur
`data-value`	Item	öğenin değeri

Erişilebilirlik

Listbox'ı hep görünen WAI-ARIA Combobox desenini izler. Focus input'tan hiç ayrılmaz; aktif seçenek aria-activedescendant ile bildirilir, sonuç sayısı polite bir live region'da okunur. Hiçbir şey eşleşmezse liste listbox olmaktan çıkar ve input aria-expanded="false" bildirir. Okunan her metin bir prop'tur.

Tuş	Ne yapar
`ArrowDown`	Sonraki öğe; sona gelince başa döner (devre dışı öğeleri atlar).
`ArrowUp`	Önceki öğe; başa gelince sona döner.
`PageUp`	İlk öğe.
`PageDown`	Son öğe.
`Enter`	Aktif öğeyi çalıştırır.
`⌘ / CtrlK`	Command.Dialog: sayfanın her yerinden açar ya da kapatır.
`Escape`	Command.Dialog: kapatır ve focus'u geri verir.

Kullanım ilkeleri

Yap

Öğeleri bir fiille ya da hedefle adlandır ("Yeni proje", "Faturalandırmaya git") ve türüne göre grupla.

Kaçın

Bir aksiyona ulaşmanın tek yolunu komut menüsü yapmak. Komut menüsü, ne istediğini bilenler için bir kısayoldur.

İlgili sayfalar

Shortcut: öğelerde gösterilen tuş kombinasyonları.
Dialog: Command.Dialog'un arkasındaki modal.
Select: bir form için tek değer seçmek.