Global Search React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Global Search is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import GlobalSearch from @/components/ui/global-search.

"use client"

import { Building2, FileWarning, Receipt } from "lucide-react"
import { GlobalSearch, type SearchResultGroup } from "@/components/ui/global-search"

type Hit = { id: string; name: string; city: string }

export function HeaderSearch() {
  return (
    <GlobalSearch
      placeholder="Search Acme CRM"
      scopes={[
        { value: "all", label: "All" },
        { value: "clients", label: "Clients", icon: <Building2 /> },
        { value: "invoices", label: "Invoices", icon: <Receipt /> },
      ]}
      loadResults={async (query, { signal, scope }): Promise<SearchResultGroup[]> => {
        const res = await fetch(`/api/search?q=${encodeURIComponent(query)}&scope=${scope}`, { signal })
        const data: { clients: Hit[]; total: number } = await res.json()
        return [
          {
            id: "clients",
            label: "Clients",
            total: data.total,
            href: `/clients?q=${encodeURIComponent(query)}`,
            items: data.clients.map((c) => ({ value: c.id, label: c.name, description: c.city, href: `/clients/${c.id}` })),
          },
        ]
      }}
      suggestions={[{ value: "overdue", label: "Overdue invoices", icon: <FileWarning />, href: "/invoices/overdue" }]}
      onSubmit={(query) => console.log("search everywhere:", query)}
    />
  )
}

Props

• results
  SearchResultGroup[]

  Static results filtered locally as you type (label, textValue, keywords and a text description; case and diacritics never matter). A group is { id?, label, items, total?, href? }; a result is a listbox option { value, label, description?, icon?, badge?, keywords? } plus href?, external? and meta? (a trailing amount or date).

• loadResults
  (query: string, context: { signal: AbortSignal; scope: string }) => Promise<SearchResultGroup[]>

  Server search, used instead of results: debounced, the previous request aborted, the last 20 answers cached, the old results kept while the new ones load; a rejected promise shows an error with Try again. A group with href and total > items.length ends in a See all row.

• suggestions
  SearchResult[]

  Quick links under the recents while the query is empty (“Overdue invoices”, “New clients this month”).

• scopes
  SearchScope[]

  Chips above the results ({ value, label, icon? }): loadResults gets the scope; static results narrow to the group whose id equals it (any other value, like “all”, keeps every group).

• placeholderdefault "Search"
  string

  The field's placeholder and accessible name, also on the phone trigger.

• labels
  Partial<GlobalSearchLabels>

  Every string: title, recent, suggestions, seeAll(total, label), searchFor(query, scope?), cancel, clearRecent, removeRecent, noResults(query), results(count, formatted), scopeHint, scopes, searchIn(scope), navigate, open, close, clear, loading, error, retry, minQuery(min), idle. English defaults.

• sizedefault "md"
  "sm" | "md" | "lg"

  The field box: 32 / 40 / 48px (md is 44px on touch).

• variantdefault "soft"
  "soft" | "outline" | "ghost"

  The field look: a filled well, an outlined box, or bare until hovered.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner radius of the field, scaled with its size like the button's.

• widthdefault 320
  number

  Resting width of the desktop field in px (capped by its container).

• expandedWidthdefault 480
  number

  Width while focused or open, and the minimum width of the results panel. The field grows to it on a spring.

• mobileTriggerdefault "icon"
  "icon" | "field"

  Phones: a 44px search icon for a bar, or a full-width field-looking button; both open the full-screen search.

• showShortcutdefault true
  boolean

  The key hint at the end of the field while it is empty and not focused (never on touch).

• highlightMatchesdefault true
  boolean

  Matched letters of string labels in bold.

• defaultOpendefault false
  boolean

  Starts with the panel (desktop) or the full-screen search (phones) open. Use open and onOpenChange to control it.

• open
  boolean

  Controlled open state of the panel or overlay; pair it with onOpenChange.

• onOpenChange
  (open: boolean) => void

  Fires when the panel or overlay opens or closes.

• value
  string

  Controlled query; defaultValue (default "") and onValueChange complete the pair.

• defaultValuedefault ""
  string

  The query it starts with while uncontrolled.

• onValueChange
  (value: string) => void

  Fires on every keystroke, and when a recent query is picked or the text is cleared.

• scope
  string

  Controlled scope (a scope value); defaultScope (default: the first scope) and onScopeChange complete the pair.

• defaultScopedefault ""
  string

  The scope it starts in while uncontrolled; empty means the first scope. The demo's scopes are all (the first), clients, contacts, proposals and invoices.

• onScopeChange
  (scope: string) => void

  Fires when a chip is picked or Tab cycles the scope.

• disableddefault false
  boolean

  Dims the field, ignores input and the shortcut.

• onSubmit
  (query: string, scope: string) => void

  Enter with nothing highlighted, or the “Search for … everywhere” row: go to your full results page.

• onSelect
  (result: SearchResult) => void

  A result or suggestion was picked. Default: navigate to result.href through the LinkProvider's router (external links in a new tab).

• debouncedefault 250
  number

  Milliseconds of quiet typing before loadResults runs.

• minQueryLengthdefault 1
  number

  Characters needed before results are searched; shorter queries show a hint and the recents stay hidden.

• shortcutdefault "/"
  string

  Focuses the field from anywhere (opens the full-screen search on phones), never while typing in another field. "" binds nothing. The showcase binds “/” itself, so the demo uses S while this is “/”.

• recentdefault true
  boolean

  Remembers submitted queries and opened results, shown while the query is empty (a repeat moves to the top).

• recentKeydefault "global-search:recent"
  string

  Local storage key for the recents (use-persisted-state), synced across tabs. "" keeps them in memory.

• maxRecentdefault 5
  number

  How many recents to keep.

• defaultRecent
  string[]

  Recent queries shown while nothing is stored yet (first visit, onboarding).

• onRecentChange
  (recent: GlobalSearchRecent[]) => void

  Fires when a recent is added, removed or cleared, e.g. to sync them to the user's account.

• responsivedefault true
  boolean

  Below 768px the field becomes the phone trigger and opens a full-screen search.

• modedefault "auto"
  "auto" | "popover" | "overlay"

  auto follows the screen (with responsive); popover keeps the field and its panel everywhere; overlay always uses the phone trigger and the full-screen search.

• localedefault ""
  string

  Formats the result counts in the footer and the announcements (“1,240 results”). Empty: the LocaleProvider's, else the browser's.

• container
  HTMLElement | null

  Portal target of the panel and the full-screen search. Default document.body.

• classNames
  Partial<Record<GlobalSearchSlot, string>>

  Classes per part: box, input, icon, shortcut, clear, content, scopes, scope, list, group, result, seeAll, recent, recentRemove, clearRecent, status, footer, searchFor, mobileTrigger, overlay, cancel.

FAQ

Used in

More React navigation components