⚡ Professional Command Palette (⌘K) for React & Next.js - Tailwind-native, 20+ themes, built-in calculator, unit converter, recent searches, bookmarks, shortcuts panel. Alternative to cmdk/kbar.
npm install spotlight-omni-searchSpotlightProvider.
SearchTrigger button.
2 + 2 and get instant results!
100 km to miles, 32 F to C, and more!
? to view all keyboard shortcuts.
Cmd+K, Arrow keys).
? to view | ❌ | ❌ |
bash
npm install spotlight-omni-search
`
> Note: Icons are optional! Use any icon library you prefer (Lucide, Material Icons, Heroicons, custom SVGs, or no icons). See Icon Guide for examples.
---
⚡ Quick Start
$3
`tsx
// app/layout.tsx
"use client";
import { SpotlightProvider, SearchTrigger } from "spotlight-omni-search/next";
import { useRouter } from "next/navigation";
export default function RootLayout({ children }) {
const router = useRouter();
const items = [
{ id: "home", label: "Home", route: "/" },
{ id: "docs", label: "Documentation", route: "/docs" },
{
id: "theme",
label: "Toggle Theme",
action: () => console.log("Theme toggled"),
},
];
return (
onNavigate={(path) => router.push(path)}
theme="dark" // Try: 'light', 'slate', 'blue', 'rose'
>
{children}
);
}
`
$3
`tsx
import { SpotlightProvider, SearchTrigger } from "spotlight-omni-search/react";
import { useNavigate } from "react-router-dom";
function App() {
const navigate = useNavigate();
const items = [{ id: "dashboard", label: "Dashboard", route: "/dashboard" }];
return (
);
}
`
---
🎨 Ready-to-Use Templates
Get started in 30 seconds with pre-configured templates! Perfect for common use cases.
$3
Pre-configured for SaaS applications with navigation, quick actions, billing, and all v2.5.0 plugins.
`tsx
import { SaaSDashboardTemplate } from "spotlight-omni-search";
function App() {
return (
);
}
`
Includes:
- Navigation (Dashboard, Analytics, Users, Settings)
- Quick Actions (New Project, Invite User, Export Data)
- Billing & Subscription
- Theme Switcher
- All v2.5.0 plugins (Calculator, Unit Converter, Recent Searches, Bookmarks, Shortcuts Panel)
$3
Perfect for documentation websites with guides, API reference, and examples.
`tsx
import { DocsTemplate } from "spotlight-omni-search";
function App() {
return (
);
}
`
Includes:
- Documentation (Getting Started, API Reference, Guides, Components)
- Examples & Playground
- Community Links (GitHub, Discord)
- Version Switcher
- Calculator, Unit Converter, Shortcuts Panel
$3
Comprehensive admin dashboard with user management and system controls.
`tsx
import { AdminPanelTemplate } from "spotlight-omni-search";
function App() {
return (
);
}
`
Includes:
- User Management (Users, Roles, Permissions)
- System Settings (Config, Logs, Monitoring)
- Analytics & Reports
- Database Management
- Danger Zone (with confirmations)
- All plugins enabled
$3
Templates are just configuration objects. Customize them easily:
`tsx
import { SaaSDashboardTemplate } from "spotlight-omni-search";
const customTemplate = {
...SaaSDashboardTemplate,
theme: "violet", // Change theme
items: [
...SaaSDashboardTemplate.items,
{ id: "custom", label: "My Custom Action", type: "action" },
],
};
;
`
---
📁 File Search Plugin
Search for files in your project with fuzzy matching, file icons, and metadata.
$3
`tsx
import { FileSearchPlugin } from "spotlight-omni-search";
const files = [
{ id: "1", path: "/src/App.tsx", name: "App.tsx", extension: "tsx" },
{
id: "2",
path: "/src/components/Button.tsx",
name: "Button.tsx",
extension: "tsx",
},
];
plugins={[
FileSearchPlugin({
files,
onFileSelect: (file) => openFile(file.path),
}),
]}
>
;
`
Usage: Type @ to activate file search, then type your query (e.g., @app to find App.tsx).
$3
- Trigger Prefix: Type @ to activate file search mode
- Fuzzy Matching: Matches file names, paths, and directories
- File Icons: Automatic icons based on file extension (20+ types)
- Metadata: Shows file size and last modified date
- Recent Files: Tracks recently opened files
- Async Search: Supports dynamic file loading from APIs
$3
`tsx
FileSearchPlugin({
files,
showMetadata: true, // Show size and date
showIcons: true, // Show file type icons
onFileSelect: (file) => console.log("Open:", file.path),
});
`
$3
`tsx
FileSearchPlugin({
onSearch: async (query) => {
const response = await fetch(/api/files?q=${query});
return await response.json(); // Returns FileItem[]
},
triggerPrefix: "@",
maxResults: 10,
});
`
$3
Supported file types with automatic icons:
- Code: .ts, .tsx, .js, .jsx, .py, .java, .cpp
- Styles: .css, .scss, .sass, .less
- Config: .json, .yaml, .yml, .xml
- Docs: .md, .mdx, .txt, .pdf
- Images: .png, .jpg, .svg, .gif, .webp
---
🎯 Multi-Select Mode (Coming in v3.0.0)
Select multiple items and perform bulk actions - perfect for admin panels and file managers.
> Note: Multi-Select Mode is currently in development and will be available in v3.0.0. The API is finalized and ready to use.
$3
- ✅ Checkbox UI (visible on hover/selection)
- ✅ Ctrl/Cmd + Click to toggle selection
- ✅ Select All / Deselect All buttons
- ✅ Bulk action toolbar
- ✅ Custom bulk actions
- ✅ Keyboard shortcuts (Ctrl+A, Escape)
$3
`tsx
import { SpotlightProvider } from "spotlight-omni-search";
multiSelect={true}
onMultiSelect={(selectedItems) => {
console.log("Selected:", selectedItems);
}}
>
;
`
$3
`tsx
const bulkActions = [
{
id: "delete",
label: "Delete Selected",
icon:
variant: "danger",
action: (items) => {
console.log("Deleting:", items);
deleteItems(items);
},
},
{
id: "export",
label: "Export Selected",
icon:
action: (items) => {
exportItems(items);
},
},
];
multiSelect={true}
multiSelectActions={bulkActions}
>
;
`
$3
- Ctrl/Cmd + Click: Toggle item selection
- Ctrl/Cmd + A: Select all visible items
- Escape: Clear selection
---
🏷️ Tags & Categories
Organize and filter items using tags and categories for better discoverability in large datasets.
$3
`tsx
const items: SpotlightItem[] = [
{
id: "1",
label: "User Management",
description: "Manage users and permissions",
type: "page",
category: "Administration",
tags: ["admin", "users", "security"],
},
{
id: "2",
label: "Create Post",
description: "Write a new blog post",
type: "action",
category: "Content",
tags: ["content", "editor", "new"],
},
];
;
`
$3
Use the tag: prefix to filter items by tags:
`tsx
// User searches: "tag:admin"
// Shows only items with 'admin' tag
// User searches: "tag:admin tag:urgent"
// Shows items with BOTH 'admin' AND 'urgent' tags
// User searches: "user tag:admin"
// Shows items containing "user" AND tagged with 'admin'
`
$3
`tsx
const tagColors = {
admin: "#8b5cf6", // purple
urgent: "#ef4444", // red
beta: "#ec4899", // pink
new: "#14b8a6", // teal
};
tagColors={tagColors}
showTags={true}
tagFilterPrefix="tag:" // default
>
;
`
$3
`tsx
const items: SpotlightItem[] = [
{
id: "1",
label: "Critical Alert",
tags: ["urgent", "security"],
tagColors: {
urgent: "#dc2626", // custom red for this item
},
},
];
`
$3
Categories are used for visual grouping in the results:
`tsx
const items: SpotlightItem[] = [
{
id: "1",
label: "User Settings",
category: "Administration",
tags: ["admin"],
},
{
id: "2",
label: "Role Management",
category: "Administration",
tags: ["admin"],
},
{ id: "3", label: "Create Post", category: "Content", tags: ["content"] },
{ id: "4", label: "Media Library", category: "Content", tags: ["content"] },
];
`
Results will be grouped by category:
`
Administration
- User Settings [admin]
- Role Management [admin]
Content
- Create Post [content]
- Media Library [content]
`
$3
| Search Query | Result |
| --------------------------------- | ----------------------------------------------- |
| tag:admin | All items with 'admin' tag |
| tag:admin tag:urgent | Items with BOTH tags (AND logic) |
| user tag:admin | Items containing "user" AND tagged with 'admin' |
| tag:beta | All beta features |
| settings tag:admin tag:security | "settings" + admin + security tags |
$3
`tsx
// Global tag colors
tagColors={{
admin: "#8b5cf6",
urgent: "#ef4444",
}}
// Show/hide tag badges
showTags={true} // default: true
// Custom tag filter prefix
tagFilterPrefix="tag:" // default: 'tag:'
>
`
---
🧩 Advanced Usage
$3
Fetch results dynamically as the user types.
`tsx
onSearch={async (query) => {
const response = await fetch(/api/search?q=${query});
return await response.json(); // Returns SpotlightItem[]
}}
onNavigate={navigate}
>
{/ ... /}
`
$3
Prevent accidental actions with built-in confirmation dialogs.
`tsx
const items = [
{
id: "delete-account",
label: "Delete Account",
group: "Danger Zone",
confirm: {
title: "Are you sure?",
message: "This action cannot be undone.",
type: "danger", // Red color theme
},
action: () => deleteAccount(),
},
];
`
$3
Create powerful commands that accept user input (e.g., "Google [query]").
`tsx
{
id: "google-search",
label: "Search Google",
expectsArguments: true, // Captures text after the command
action: (query) => window.open(https://google.com/search?q=${query})
}
`
$3
Evaluate math expressions directly in the search bar!
`tsx
import { SpotlightProvider } from "spotlight-omni-search/next";
import { CalculatorPlugin } from "spotlight-omni-search";
plugins={[
CalculatorPlugin({
enableClipboardCopy: true, // Auto-copy result to clipboard
precision: 10, // Decimal precision
icon:
})
]}
onNavigate={navigate}
>
`
Try it:
- Type 2 + 2 → Get 4
- Type (10 + 5) * 2 → Get 30
- Type 2 ^ 8 → Get 256
- Press Enter to copy result to clipboard!
Supported operators: +, -, *, /, %, ^ (exponentiation)
Security: Safe evaluation - blocks dangerous code like alert(), window, etc.
$3
Convert units on the fly - length, weight, temperature, and volume!
`tsx
import { UnitConverterPlugin } from "spotlight-omni-search";
plugins={[
UnitConverterPlugin({
enableClipboardCopy: true,
icon:
})
]}
>
`
Try it:
- Type 100 km to miles → Get 62.14 miles
- Type 32 F to C → Get 0°C
- Type 5 kg to pounds → Get 11.02 lb
- Type 2 liters to gallons → Get 0.53 gal
Supported conversions: Length, Weight, Temperature, Volume
$3
Track and display search history for quick access.
`tsx
import { RecentSearchesPlugin } from "spotlight-omni-search";
plugins={[
RecentSearchesPlugin({
maxSearches: 10,
showInResults: true,
enableObfuscation: true // Privacy protection
})
]}
>
`
Features:
- Shows recent searches when input is empty
- Click to re-run previous searches
- Privacy-protected with obfuscation
- "Clear Recent Searches" action
$3
Star your favorite commands for quick access!
`tsx
import { BookmarksPlugin } from "spotlight-omni-search";
plugins={[
BookmarksPlugin({
maxBookmarks: 20,
showAtTop: true,
bookmarkIcon:
})
]}
>
`
Features:
- Bookmark frequently used commands
- Bookmarks appear at top of results
- Manage and clear bookmarks
- Persistent across sessions
$3
Never forget a shortcut again!
`tsx
import { ShortcutsPanelPlugin } from "spotlight-omni-search";
plugins={[
ShortcutsPanelPlugin({
triggerKey: '?',
customShortcuts: [
{ key: 'Ctrl+B', description: 'Bookmark item', category: 'Actions' }
]
})
]}
>
`
Features:
- Press ? to view all shortcuts
- Organized by category
- Add custom shortcuts
- Searchable reference
$3
Make commands easier to find with alternative names!
`tsx
const items = [
{
id: "settings",
label: "Settings",
aliases: ["preferences", "config", "options", "prefs"],
route: "/settings",
},
];
`
Benefits:
- Type "prefs" → finds "Settings"
- Type "config" → finds "Settings"
- More forgiving search
- Better discoverability
---
$3
Evaluate math expressions directly in the search bar!
`tsx
import { SpotlightProvider } from "spotlight-omni-search/next";
import { CalculatorPlugin } from "spotlight-omni-search";
plugins={[
CalculatorPlugin({
enableClipboardCopy: true, // Auto-copy result to clipboard
precision: 10, // Decimal precision
icon:
})
]}
onNavigate={navigate}
>
`
Try it:
- Type 2 + 2 → Get 4
- Type (10 + 5) * 2 → Get 30
- Type 2 ^ 8 → Get 256
- Press Enter to copy result to clipboard!
Supported operators: +, -, *, /, %, ^ (exponentiation)
Security: Safe evaluation - blocks dangerous code like alert(), window, etc.
$3
Track searches and selections locally.
`tsx
import { AnalyticsPlugin } from "spotlight-omni-search";
const analytics = AnalyticsPlugin({
enableSessionTracking: true,
onSearch: (query) => console.log("Searching:", query),
onSelect: (id, type) => console.log("Selected:", id),
});
// ... inside plugins prop
plugins: [analytics];
// Export data later
console.log(analytics.exportData("csv"));
`
$3
seamless integration with GA4.
`tsx
import { GoogleAnalyticsPlugin } from "spotlight-omni-search";
plugins: [
GoogleAnalyticsPlugin({
measurementId: "G-XXXXXXXXXX",
enableDebug: true, // Log events to console
loadScript: true, // Auto-inject GA script
}),
];
`
$3
Create folder-like navigation structures. When an item with items array is selected, it "zooms in" to those items.
`tsx
import { NestedCommandsPlugin } from "spotlight-omni-search";
import { NestedPlugin } from "spotlight-omni-search/plugins/nested"; // or from main export if available
plugins: [
NestedCommandsPlugin({
backKey: "Backspace", // 'Backspace' or 'Escape' to go up a level
}),
];
// Item Structure
const items = [
{
id: "settings",
label: "Settings",
items: [
// Children
{ id: "profile", label: "Profile" },
{ id: "billing", label: "Billing" },
],
},
];
`
$3
Optimize performance for large lists by rendering only a window of results.
`tsx
import { VirtualScrollingPlugin } from "spotlight-omni-search";
plugins: [
VirtualScrollingPlugin({
windowSize: 20, // Only render 20 items at a time
itemHeight: 40,
}),
];
`
---
🎨 Layouts & Themes
Themes: light dark slate rose blue orange emerald violet ... (and many more)
Layouts:
- center: Classic modal (default)
- top: Command palette style
- fullscreen: Immersive search
- side-right: Drawer style
`tsx
layout="top"
items={items}
>
`
---
💅 Custom Styling
You can granularly style every part of the component using classNames or specific props like headerClassName.
`tsx
className="shadow-2xl rounded-xl border-blue-100" // Main container style
headerClassName="z-[9999] border-b-2 border-primary" // Header style
itemClassName="hover:bg-primary/10 transition-colors" // Default item style
// Advanced: Granular overrides still available
classNames={{
itemSelected: 'bg-primary/20'
}}
>
`
---
🔒 Privacy & Security
Spotlight automatically obfuscates sensitive data stored in localStorage` (like search history and recent items) using Base64 encoding. This prevents casual inspection of user data in the browser dev tools.