What is Search Dialog?

Search Dialog is a React command-palette component from VLLNT UI. It opens a modal search over a list of items, highlights matches, and supports optional asynchronous documentation search across scoped tabs.

How do I add Search Dialog?

Run `pnpm dlx shadcn@latest add https://ui.vllnt.com/r/search-dialog.json` to install Search Dialog via the shadcn CLI. The component and its types are copied into your project so you can wire it to your data.

Does Search Dialog support a keyboard shortcut?

Yes. It listens for Cmd+K (or Ctrl+K) to toggle open and shows a shortcut badge on the trigger button. The shortcut is ignored while typing in inputs, and you can turn it off with the enableKeyboardShortcut prop.

Search Dialog

Full-screen search dialog with keyboard navigation. Install Search Dialog from the VLLNT UI registry with the shadcn CLI.

Report a bug

What it is and when to use

Search Dialog is a command-palette search built on the Command component. A trigger button and a Cmd/Ctrl+K shortcut open a modal where users type to filter items, with matching text highlighted and results sorted by title. Supply an async docsSearch function to enable Components, Docs, and Everything scope tabs with loading and empty states, and onSelect callbacks handle navigation. Use it for site-wide search, docs lookup, or in-app navigation.

Learning

Full-screen search dialog with keyboard navigation. Part of the learning family in VLLNT UI, it ships as a machine-readable registry entry — copy the source directly into your app with the shadcn CLI and own it, no runtime dependency on a component library.

Preview

Switch between light and dark to inspect the embedded Storybook preview.

Installation

Add Search Dialog to your project with the shadcn CLI. The source lands in your codebase, ready to adapt:

pnpm dlx shadcn@latest add https://ui.vllnt.com/r/search-dialog.json

Source

"use client";

import {
  useCallback,
  useEffect,
  useId,
  useMemo,
  useRef,
  useState,
} from "react";

import { Search } from "lucide-react";

import { cn } from "../../lib/utils";
import { Button } from "../button/button";
import {
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
} from "../command/command";

export type SearchItem = {
  description?: string;
  href?: string;
  id: string;
  keywords?: string;
  snippet?: string;
  title: string;
};

type SearchScope = "components" | "docs" | "everything";

function useKeyboardShortcut(callback: () => void) {
  useEffect(() => {
    const down = (event: KeyboardEvent) => {
      if (
        (event.key === "k" || event.key === "K") &&
        (event.metaKey || event.ctrlKey)
      ) {
        const target = event.target as HTMLElement | null;
        if (
          target &&
          (target.tagName === "INPUT" ||
            target.tagName === "TEXTAREA" ||
            target.isContentEditable)
        ) {
          return;
        }

        event.preventDefault();
        event.stopPropagation();
        event.stopImmediatePropagation();
        callback();
      }
    };

    window.addEventListener("keydown", down, { capture: true, passive: false });
    return () => {
      window.removeEventListener("keydown", down, { capture: true });
    };
  }, [callback]);
}

type SearchDialogProps = {
  buttonText?: string;
  buttonTextMobile?: string;
  docsEmptyText?: string;
  docsGroupHeading?: string;
  docsSearch?: (query: string) => Promise<SearchItem[]>;
  emptyText?: string;
  enableKeyboardShortcut?: boolean;
  groupHeading?: string;
  items: SearchItem[];
  minDocsSearchLength?: number;
  onDocsSelect?: (item: SearchItem) => void;
  onSelect: (item: SearchItem) => void;
  scopeLabels?: Partial<Record<SearchScope, string>>;
  searchPlaceholder?: string;
};

const DEFAULT_SCOPE_LABELS: Record<SearchScope, string> = {
  components: "Components",
  docs: "Docs",
  everything: "Everything",
};

function getItemValue(item: SearchItem) {
  return [
    item.title,
    item.description,
    item.snippet,
    item.keywords,
    item.href,
    item.id,
  ]
    .filter(Boolean)
    .join(" ");
}

function HighlightedText({ query, text }: { query: string; text: string }) {
  const trimmedQuery = query.trim();

  if (!trimmedQuery) {
    return text;
  }

  const index = text.toLowerCase().indexOf(trimmedQuery.toLowerCase());

  if (index === -1) {
    return text;
  }

  return (
    <>
      {text.slice(0, index)}
      <mark className="rounded bg-primary/15 px-0.5 text-foreground">
        {text.slice(index, index + trimmedQuery.length)}
      </mark>
      {text.slice(index + trimmedQuery.length)}
    </>
  );
}

function ScopeTabs({
  getTabId,
  labels,
  onScopeChange,
  panelId,
  scope,
}: {
  getTabId: (s: SearchScope) => string;
  labels: Record<SearchScope, string>;
  onScopeChange: (scope: SearchScope) => void;
  panelId: string;
  scope: SearchScope;
}) {
  const scopes: SearchScope[] = ["components", "docs", "everything"];

  return (
    <div
      aria-label="Search scope"
      className="grid grid-cols-3 gap-1 border-b p-1"
      role="tablist"
    >
      {scopes.map((nextScope) => (
        <button
          aria-controls={panelId}
          aria-selected={scope === nextScope}
          className={cn(
            "h-8 rounded-sm px-2 text-xs font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground",
            scope === nextScope && "bg-accent text-accent-foreground",
          )}
          id={getTabId(nextScope)}
          key={nextScope}
          onClick={() => {
            onScopeChange(nextScope);
          }}
          role="tab"
          type="button"
        >
          {labels[nextScope]}
        </button>
      ))}
    </div>
  );
}

function SearchResultContent({
  item,
  query,
}: {
  item: SearchItem;
  query: string;
}) {
  return (
    <div className="flex min-w-0 flex-col">
      <span className="truncate font-medium">{item.title}</span>
      {item.snippet ? (
        <span className="line-clamp-2 text-xs text-muted-foreground">
          <HighlightedText query={query} text={item.snippet} />
        </span>
      ) : item.description ? (
        <span className="line-clamp-2 text-xs text-muted-foreground">
          {item.description}
        </span>
      ) : null}
    </div>
  );
}

function SearchTriggerButton({
  buttonText,
  buttonTextMobile,
  onOpen,
}: {
  buttonText?: string;
  buttonTextMobile?: string;
  onOpen: () => void;
}) {
  return (
    <Button
      className={cn(
        "relative h-9 w-full justify-start text-sm text-muted-foreground sm:pr-12 md:w-40 lg:w-64",
      )}
      onClick={onOpen}
      variant="outline"
    >
      <Search className="mr-2 size-4" />
      <span className="hidden lg:inline-flex">{buttonText ?? "Search..."}</span>
      <span className="inline-flex lg:hidden">
        {buttonTextMobile ?? "Search..."}
      </span>
      <kbd className="pointer-events-none absolute right-1.5 top-1.5 hidden h-5 select-none items-center gap-1 rounded border bg-muted px-1.5 font-mono text-[10px] font-medium opacity-100 sm:flex">
        <span className="text-xs">⌘</span>K
      </kbd>
    </Button>
  );
}

function ComponentResultsGroup({
  groupHeading,
  hasDocumentationSearch,
  items,
  labels,
  onSelect,
  query,
}: {
  groupHeading?: string;
  hasDocumentationSearch: boolean;
  items: SearchItem[];
  labels: Record<SearchScope, string>;
  onSelect: (item: SearchItem) => void;
  query: string;
}) {
  return (
    <CommandGroup
      heading={
        groupHeading ?? (hasDocumentationSearch ? labels.components : undefined)
      }
    >
      {items.map((item) => (
        <CommandItem
          key={item.id}
          onSelect={() => {
            onSelect(item);
          }}
          value={getItemValue(item)}
        >
          <SearchResultContent item={item} query={query} />
        </CommandItem>
      ))}
    </CommandGroup>
  );
}

function DocumentationStatusItem({
  documentationSearchLength,
  trimmedQuery,
}: {
  documentationSearchLength: number;
  trimmedQuery: string;
}) {
  return (
    <CommandItem disabled value={`${trimmedQuery} search-docs-min-length`}>
      <span className="text-sm text-muted-foreground">
        Type at least {documentationSearchLength} characters to search docs.
      </span>
    </CommandItem>
  );
}

function DocumentationLoadingItem({ trimmedQuery }: { trimmedQuery: string }) {
  return (
    <CommandItem disabled value={`${trimmedQuery} searching-docs`}>
      <span className="text-sm text-muted-foreground">Searching docs...</span>
    </CommandItem>
  );
}

function DocumentationResultsGroup({
  docsGroupHeading,
  documentationItems,
  documentationLoading,
  documentationSearchLength,
  onSelect,
  query,
  scope,
  trimmedQuery,
}: {
  docsGroupHeading?: string;
  documentationItems: SearchItem[];
  documentationLoading: boolean;
  documentationSearchLength: number;
  onSelect: (item: SearchItem) => void;
  query: string;
  scope: SearchScope;
  trimmedQuery: string;
}) {
  const showMinimumLengthPrompt =
    scope === "docs" && trimmedQuery.length < documentationSearchLength;
  const showDocumentationItems =
    !documentationLoading && trimmedQuery.length >= documentationSearchLength;

  return (
    <CommandGroup heading={docsGroupHeading ?? "Docs"}>
      {showMinimumLengthPrompt ? (
        <DocumentationStatusItem
          documentationSearchLength={documentationSearchLength}
          trimmedQuery={trimmedQuery}
        />
      ) : null}
      {documentationLoading ? (
        <DocumentationLoadingItem trimmedQuery={trimmedQuery} />
      ) : null}
      {showDocumentationItems
        ? documentationItems.map((item) => (
            <CommandItem
              key={item.id}
              onSelect={() => {
                onSelect(item);
              }}
              value={getItemValue(item)}
            >
              <SearchResultContent item={item} query={query} />
            </CommandItem>
          ))
        : null}
    </CommandGroup>
  );
}

function SearchDialogList({
  activeTabId,
  currentEmptyText,
  docsGroupHeading,
  documentationItems,
  documentationLoading,
  documentationSearchLength,
  groupHeading,
  hasDocumentationSearch,
  labels,
  onComponentSelect,
  onDocumentationSelect,
  panelId,
  query,
  scope,
  showComponents,
  showDocumentation,
  sortedItems,
  trimmedQuery,
}: {
  activeTabId?: string;
  currentEmptyText: string;
  docsGroupHeading?: string;
  documentationItems: SearchItem[];
  documentationLoading: boolean;
  documentationSearchLength: number;
  groupHeading?: string;
  hasDocumentationSearch: boolean;
  labels: Record<SearchScope, string>;
  onComponentSelect: (item: SearchItem) => void;
  onDocumentationSelect: (item: SearchItem) => void;
  panelId?: string;
  query: string;
  scope: SearchScope;
  showComponents: boolean;
  showDocumentation: boolean;
  sortedItems: SearchItem[];
  trimmedQuery: string;
}) {
  return (
    <CommandList
      aria-labelledby={activeTabId}
      className="max-h-[420px]"
      id={panelId}
      role={activeTabId === undefined ? undefined : "tabpanel"}
    >
      <CommandEmpty>{currentEmptyText}</CommandEmpty>
      {showComponents ? (
        <ComponentResultsGroup
          groupHeading={groupHeading}
          hasDocumentationSearch={hasDocumentationSearch}
          items={sortedItems}
          labels={labels}
          onSelect={onComponentSelect}
          query={query}
        />
      ) : null}
      {showDocumentation ? (
        <DocumentationResultsGroup
          docsGroupHeading={docsGroupHeading}
          documentationItems={documentationItems}
          documentationLoading={documentationLoading}
          documentationSearchLength={documentationSearchLength}
          onSelect={onDocumentationSelect}
          query={query}
          scope={scope}
          trimmedQuery={trimmedQuery}
        />
      ) : null}
    </CommandList>
  );
}

type DocumentationSearchOptions = {
  docsSearch?: (query: string) => Promise<SearchItem[]>;
  minDocsSearchLength?: number;
};

function useDocumentationSearch({
  docsSearch,
  minDocsSearchLength,
}: DocumentationSearchOptions) {
  const [documentationItems, setDocumentationItems] = useState<SearchItem[]>(
    [],
  );
  const [documentationLoading, setDocumentationLoading] = useState(false);
  const activeDocumentationRequest = useRef(0);
  const documentationSearchLength = minDocsSearchLength ?? 2;

  const runDocumentationSearch = useCallback(
    (nextQuery: string, nextScope: SearchScope) => {
      const nextTrimmedQuery = nextQuery.trim();
      const nextRequest = activeDocumentationRequest.current + 1;
      activeDocumentationRequest.current = nextRequest;

      if (
        !docsSearch ||
        nextScope === "components" ||
        nextTrimmedQuery.length < documentationSearchLength
      ) {
        setDocumentationItems([]);
        setDocumentationLoading(false);
        return;
      }

      setDocumentationLoading(true);

      docsSearch(nextTrimmedQuery)
        .then((results) => {
          if (activeDocumentationRequest.current === nextRequest) {
            setDocumentationItems(results);
          }
        })
        .catch(() => {
          if (activeDocumentationRequest.current === nextRequest) {
            setDocumentationItems([]);
          }
        })
        .finally(() => {
          if (activeDocumentationRequest.current === nextRequest) {
            setDocumentationLoading(false);
          }
        });
    },
    [docsSearch, documentationSearchLength],
  );

  return {
    documentationItems,
    documentationLoading,
    documentationSearchLength,
    hasDocumentationSearch: docsSearch !== undefined,
    runDocumentationSearch,
  };
}

type SearchDialogHandlersOptions = {
  enableKeyboardShortcut?: boolean;
  onDocsSelect?: (item: SearchItem) => void;
  onSelect: (item: SearchItem) => void;
  runDocumentationSearch: (query: string, scope: SearchScope) => void;
};

function useSearchDialogHandlers({
  enableKeyboardShortcut,
  onDocsSelect,
  onSelect,
  runDocumentationSearch,
}: SearchDialogHandlersOptions) {
  const [open, setOpen] = useState(false);
  const [query, setQuery] = useState("");
  const [scope, setScope] = useState<SearchScope>("components");

  const toggleOpen = useCallback(() => {
    if (enableKeyboardShortcut ?? true) {
      setOpen((previous) => !previous);
    }
  }, [enableKeyboardShortcut]);

  useKeyboardShortcut(toggleOpen);

  const handleQueryChange = useCallback(
    (nextQuery: string) => {
      setQuery(nextQuery);
      runDocumentationSearch(nextQuery, scope);
    },
    [runDocumentationSearch, scope],
  );

  const handleScopeChange = useCallback(
    (nextScope: SearchScope) => {
      setScope(nextScope);
      runDocumentationSearch(query, nextScope);
    },
    [query, runDocumentationSearch],
  );

  const handleOpenChange = useCallback(
    (nextOpen: boolean) => {
      setOpen(nextOpen);

      if (nextOpen) {
        runDocumentationSearch(query, scope);
      }
    },
    [query, runDocumentationSearch, scope],
  );

  const handleComponentSelect = useCallback(
    (item: SearchItem) => {
      setOpen(false);
      onSelect(item);
    },
    [onSelect],
  );

  const handleDocumentationSelect = useCallback(
    (item: SearchItem) => {
      setOpen(false);
      (onDocsSelect ?? onSelect)(item);
    },
    [onDocsSelect, onSelect],
  );

  return {
    handleComponentSelect,
    handleDocumentationSelect,
    handleOpenChange,
    handleQueryChange,
    handleScopeChange,
    open,
    query,
    scope,
  };
}

function getCurrentEmptyText({
  docsEmptyText,
  documentationSearchLength,
  emptyText,
  scope,
  trimmedQuery,
}: {
  docsEmptyText?: string;
  documentationSearchLength: number;
  emptyText?: string;
  scope: SearchScope;
  trimmedQuery: string;
}) {
  if (scope === "docs" && trimmedQuery.length < documentationSearchLength) {
    return `Type at least ${documentationSearchLength} characters to search docs.`;
  }

  if (scope === "docs") {
    return docsEmptyText ?? "No docs found.";
  }

  return emptyText ?? "No results found.";
}

type SearchDialogViewProps = Pick<
  SearchDialogProps,
  | "buttonText"
  | "buttonTextMobile"
  | "docsGroupHeading"
  | "groupHeading"
  | "searchPlaceholder"
> & {
  currentEmptyText: string;
  documentationSearch: ReturnType<typeof useDocumentationSearch>;
  handlers: ReturnType<typeof useSearchDialogHandlers>;
  labels: Record<SearchScope, string>;
  showDocumentation: boolean;
  sortedItems: SearchItem[];
  trimmedQuery: string;
};

function SearchDialogView({
  buttonText,
  buttonTextMobile,
  currentEmptyText,
  docsGroupHeading,
  documentationSearch,
  groupHeading,
  handlers,
  labels,
  searchPlaceholder,
  showDocumentation,
  sortedItems,
  trimmedQuery,
}: SearchDialogViewProps) {
  const baseId = useId();
  const getTabId = (s: SearchScope) => `${baseId}-tab-${s}`;
  const panelId = `${baseId}-panel`;

  return (
    <>
      <SearchTriggerButton
        buttonText={buttonText}
        buttonTextMobile={buttonTextMobile}
        onOpen={() => {
          handlers.handleOpenChange(true);
        }}
      />
      <CommandDialog
        onOpenChange={handlers.handleOpenChange}
        open={handlers.open}
      >
        <CommandInput
          onValueChange={handlers.handleQueryChange}
          placeholder={searchPlaceholder ?? "Search..."}
          value={handlers.query}
        />
        {documentationSearch.hasDocumentationSearch ? (
          <ScopeTabs
            getTabId={getTabId}
            labels={labels}
            onScopeChange={handlers.handleScopeChange}
            panelId={panelId}
            scope={handlers.scope}
          />
        ) : null}
        <SearchDialogList
          activeTabId={
            documentationSearch.hasDocumentationSearch
              ? getTabId(handlers.scope)
              : undefined
          }
          currentEmptyText={currentEmptyText}
          docsGroupHeading={docsGroupHeading}
          documentationItems={documentationSearch.documentationItems}
          documentationLoading={documentationSearch.documentationLoading}
          documentationSearchLength={
            documentationSearch.documentationSearchLength
          }
          groupHeading={groupHeading}
          hasDocumentationSearch={documentationSearch.hasDocumentationSearch}
          labels={labels}
          onComponentSelect={handlers.handleComponentSelect}
          onDocumentationSelect={handlers.handleDocumentationSelect}
          panelId={
            documentationSearch.hasDocumentationSearch ? panelId : undefined
          }
          query={handlers.query}
          scope={handlers.scope}
          showComponents={handlers.scope !== "docs"}
          showDocumentation={showDocumentation}
          sortedItems={sortedItems}
          trimmedQuery={trimmedQuery}
        />
      </CommandDialog>
    </>
  );
}

export function SearchDialog({
  buttonText,
  buttonTextMobile,
  docsEmptyText,
  docsGroupHeading,
  docsSearch,
  emptyText,
  enableKeyboardShortcut,
  groupHeading,
  items,
  minDocsSearchLength,
  onDocsSelect,
  onSelect,
  scopeLabels,
  searchPlaceholder,
}: SearchDialogProps) {
  const documentationSearch = useDocumentationSearch({
    docsSearch,
    minDocsSearchLength,
  });
  const handlers = useSearchDialogHandlers({
    enableKeyboardShortcut,
    onDocsSelect,
    onSelect,
    runDocumentationSearch: documentationSearch.runDocumentationSearch,
  });
  const labels = { ...DEFAULT_SCOPE_LABELS, ...scopeLabels };
  const trimmedQuery = handlers.query.trim();
  const sortedItems = useMemo(
    () => [...items].sort((a, b) => a.title.localeCompare(b.title)),
    [items],
  );
  const currentEmptyText = getCurrentEmptyText({
    docsEmptyText,
    documentationSearchLength: documentationSearch.documentationSearchLength,
    emptyText,
    scope: handlers.scope,
    trimmedQuery,
  });
  const showDocumentation =
    documentationSearch.hasDocumentationSearch &&
    handlers.scope !== "components";

  return (
    <SearchDialogView
      buttonText={buttonText}
      buttonTextMobile={buttonTextMobile}
      currentEmptyText={currentEmptyText}
      docsGroupHeading={docsGroupHeading}
      documentationSearch={documentationSearch}
      groupHeading={groupHeading}
      handlers={handlers}
      labels={labels}
      searchPlaceholder={searchPlaceholder}
      showDocumentation={showDocumentation}
      sortedItems={sortedItems}
      trimmedQuery={trimmedQuery}
    />
  );
}

Stories

Explore every variant and state in the interactive Storybook:

Preview

Switch between light and dark to inspect the embedded Storybook preview.

Dependencies

@vllnt/ui@^0.3.0

FAQ

What is Search Dialog?: Search Dialog is a React command-palette component from VLLNT UI. It opens a modal search over a list of items, highlights matches, and supports optional asynchronous documentation search across scoped tabs.
How do I add Search Dialog?: Run `pnpm dlx shadcn@latest add https://ui.vllnt.com/r/search-dialog.json` to install Search Dialog via the shadcn CLI. The component and its types are copied into your project so you can wire it to your data.
Does Search Dialog support a keyboard shortcut?: Yes. It listens for Cmd+K (or Ctrl+K) to toggle open and shows a shortcut badge on the trigger button. The shortcut is ignored while typing in inputs, and you can turn it off with the enableKeyboardShortcut prop.

Share this component

Share on X Share on LinkedIn Share on Facebook Share on Mastodon Share on Bluesky Share on Threads