@k2b/ui

Spotlight search

Portable search launchers and keyboard shortcut behavior.

Page actions

Sidebar

Mobile navigation

Toolbar

TSX

import {

openSpotlightSearch,

SpotlightButton,

type SpotlightSearchResolver,

} from "@k2b/ui";

const spotlightProjects = [

{ label: "Atlas", desc: "Customer portal", value: "atlas" },

{ label: "Beacon", desc: "Operations dashboard", value: "beacon" },

{ label: "Cedar", desc: "Documentation site", value: "cedar" },

];

const resolveSpotlightProjects: SpotlightSearchResolver<string> = ({ query }) => {

const normalizedQuery = query.trim().toLowerCase();

return spotlightProjects.filter((project) =>

`${project.label} ${project.desc}`.toLowerCase().includes(normalizedQuery),

);

};

const openSearch = async () => {

await openSpotlightSearch<string>({

title: "Open project",

placeholder: "Search projects...",

noResultsText: "No matching projects.",

resolve: resolveSpotlightProjects,

});

};

<SpotlightButton variant="default" onClick={openSearch} />

<SpotlightButton variant="chip" onClick={openSearch} />

<SpotlightButton variant="sidebar" onClick={openSearch} />

<SpotlightButton variant="sidebar-mobile" onClick={openSearch} />

<SpotlightButton variant="compact" onClick={openSearch} />

<SpotlightButton variant="icon" onClick={openSearch} />

SpotlightButton launches the portable search prompt with a consistent accessible name across navigation contexts.

Use Spotlight search

Use it for a global or scoped entity search that should open from several navigation surfaces.

Import

import { openSpotlightSearch, SpotlightButton } from "@k2b/ui";

Example

const openSearch = () => openSpotlightSearch({
  title: "Open project",
  resolve: ({ query }) => projects.filter((project) => project.label.includes(query)),
});

<SpotlightButton variant="chip" onClick={openSearch} />

Variants cover default, compact, chip, sidebar, sidebar-mobile, and icon launchers.

API reference

type SpotlightButtonVariant = "default" | "compact" | "chip" | "sidebar" | "sidebar-mobile" | "icon";

type SpotlightButtonProps = {
  variant?: SpotlightButtonVariant; label?: string; title?: string; icon?: string;
  shortcut?: string; shortcutLabel?: string | false; ariaLabel?: string; disabled?: boolean; class?: string;
  onClick: () => void | Promise<void>;
};

The default variant is "default". Shortcut caps are opt-in and show only in the chip and sidebar variants; without shortcut or shortcutLabel, none show. The default title is the button label. openSpotlightSearch<T>(options) uses the prompts.search options and result and resolves to PromptSearchItem<T> | undefined; handle the selected value.

Accessibility

Every variant retains an accessible label. The component does not register or assume a keyboard shortcut. Cloud applications register context commands through the platform; standalone hosts own their keyboard behavior.

Runtime

The button renders during SSR; opening and resolving the prompt require browser code.

Shortcut caps

Pass shortcut="mod+k" to show the shortcut. This is the recommended way: the caps are platform and locale aware, as in Kbd. Use shortcutLabel only when the host already has a ready-made label; false hides it. shortcut takes precedence when both are supplied.