(Gooey liquid backdrop layer with capsule and button blobs under the SVG goo filter)",
"
(Morphing search capsule with dark frosted glass, white border highlights, and search icon)",
" (Text input with dynamic placeholder and keyboard navigation)",
" (Satellite filter button cluster with staggered spring transitions and custom SVG iconography)",
" (Expandable floating search results tray with item metadata and shortcut badges)"
],
"physics": {
"engine": "Friction-Damped Harmonic Oscillator & SVG Metaball Shader",
"description": "Slow, viscous spring physics governing capsule width compression and button translation, coupled with GPU-accelerated SVG gooey thresholding.",
"parameters": [
{
"label": "Spring Stiffness",
"value": "170"
},
{
"label": "Spring Damping (Friction)",
"value": "24"
},
{
"label": "Spring Mass",
"value": "1.0"
},
{
"label": "Gooey Blur",
"value": "5.5px Gaussian"
},
{
"label": "Gooey Matrix",
"value": "20A - 9 (alpha threshold)"
},
{
"label": "Rest Width",
"value": "480px"
},
{
"label": "Active Width",
"value": "248px"
},
{
"label": "Total Width",
"value": "480px (fixed)"
}
]
},
"accessibility": {
"role": "combobox",
"aria": "The input is a role=\"combobox\" labelled by its placeholder. It controls a role=\"listbox\" of role=\"option\" results and tracks the highlighted option with aria-activedescendant. Filter buttons have aria-label, aria-pressed and title tooltips.",
"reducedMotion": "With prefers-reduced-motion, the capsule, buttons and results tray change state without spring animation.",
"keyboard": [
{
"key": "Tab",
"description": "Move between the input and the filter buttons."
},
{
"key": "ArrowDown / ArrowUp",
"description": "Move the highlight through the results."
},
{
"key": "Enter",
"description": "Submit the highlighted result, or the query if there are no results."
},
{
"key": "Escape",
"description": "Clear the query; if it is already empty, leave the input."
}
]
},
"guidelines": {
"recommended": [
"Top-level global search command bars in modern macOS or web applications",
"Interactive command palettes with categorical drill-downs",
"Desktop-inspired navigation interfaces requiring high visual polish"
],
"bestPractices": [
"Keep total container width constrained to prevent surrounding layout shifts during hover expansion",
"Provide meaningful category filters corresponding to the application's core data models",
"Pair with keyboard shortcuts (e.g. ⌘K) to open or focus the search input"
]
},
"props": [
{
"name": "value",
"type": "string",
"defaultValue": "undefined",
"description": "Controlled search query string."
},
{
"name": "defaultValue",
"type": "string",
"defaultValue": "\"\"",
"description": "Initial uncontrolled search query string."
},
{
"name": "onChange",
"type": "(value: string) => void",
"defaultValue": "undefined",
"description": "Callback fired when the search query changes."
},
{
"name": "onSubmit",
"type": "(value: string, activeFilter: SpotlightFilterId | null) => void",
"defaultValue": "undefined",
"description": "Callback fired when a search result is selected or Enter is pressed."
},
{
"name": "activeFilter",
"type": "SpotlightFilterId | null",
"defaultValue": "undefined",
"description": "Controlled active category filter ('apps' | 'folders' | 'layers' | 'docs' | null)."
},
{
"name": "onFilterChange",
"type": "(filter: SpotlightFilterId | null) => void",
"defaultValue": "undefined",
"description": "Callback fired when the active category filter changes."
},
{
"name": "placeholder",
"type": "string",
"defaultValue": "\"Spotlight Search\"",
"description": "Placeholder text shown when no filter is active."
},
{
"name": "items",
"type": "SpotlightItem[]",
"defaultValue": "DEFAULT_ITEMS",
"description": "List of searchable items with id, title, category, subtitle, and shortcut."
},
{
"name": "showResults",
"type": "boolean",
"defaultValue": "true",
"description": "Whether to display the floating results tray on input focus."
},
{
"name": "className",
"type": "string",
"defaultValue": "undefined",
"description": "Additional CSS class names for outer container."
},
{
"name": "disabled",
"type": "boolean",
"defaultValue": "false",
"description": "Whether the search bar and filter buttons are disabled."
}
],
"usage": "\"use client\";\n\nimport { SpotlightSearch } from \"@/components/ui/spotlight-search\";\n\nexport function SpotlightSearchDemo() {\n return (\n console.log(query, filter)}\n />\n );\n}",
"files": [
{
"name": "spotlight-search.tsx",
"path": "registry/ui/spotlight-search.tsx",
"code": "\"use client\";\n\nimport React, { useEffect, useId, useRef, useState, useMemo } from \"react\";\nimport {\n AnimatePresence,\n motion,\n useReducedMotion,\n type Transition,\n} from \"motion/react\";\nimport { cn } from \"@/lib/utils\";\n\nexport type SpotlightFilterId = \"apps\" | \"folders\" | \"layers\" | \"docs\";\n\nexport interface SpotlightItem {\n id: string;\n title: string;\n category: SpotlightFilterId;\n subtitle?: string;\n shortcut?: string;\n}\n\nexport interface SpotlightSearchProps {\n value?: string;\n defaultValue?: string;\n onChange?: (value: string) => void;\n onSubmit?: (value: string, activeFilter: SpotlightFilterId | null) => void;\n activeFilter?: SpotlightFilterId | null;\n onFilterChange?: (filter: SpotlightFilterId | null) => void;\n placeholder?: string;\n items?: SpotlightItem[];\n showResults?: boolean;\n className?: string;\n disabled?: boolean;\n}\n\nconst DEFAULT_ITEMS: SpotlightItem[] = [\n { id: \"1\", title: \"Xcode\", category: \"apps\", subtitle: \"Developer Tools\" },\n { id: \"2\", title: \"Safari\", category: \"apps\", subtitle: \"Web Browser\" },\n { id: \"3\", title: \"Figma\", category: \"apps\", subtitle: \"Vector Graphics\" },\n { id: \"4\", title: \"Terminal\", category: \"apps\", subtitle: \"Utilities\" },\n { id: \"5\", title: \"Music\", category: \"apps\", subtitle: \"Entertainment\" },\n {\n id: \"6\",\n title: \"Projects\",\n category: \"folders\",\n subtitle: \"~/Developer/Projects\",\n },\n { id: \"7\", title: \"Documents\", category: \"folders\", subtitle: \"~/Documents\" },\n { id: \"8\", title: \"Downloads\", category: \"folders\", subtitle: \"~/Downloads\" },\n {\n id: \"9\",\n title: \"Quick Note\",\n category: \"layers\",\n subtitle: \"Shortcut\",\n shortcut: \"⌘⇧N\",\n },\n {\n id: \"10\",\n title: \"Color Picker\",\n category: \"layers\",\n subtitle: \"Utility\",\n shortcut: \"⌥⌘C\",\n },\n {\n id: \"11\",\n title: \"design-system.fig\",\n category: \"docs\",\n subtitle: \"Figma Document\",\n },\n {\n id: \"12\",\n title: \"roadmap-2026.pdf\",\n category: \"docs\",\n subtitle: \"PDF Document\",\n },\n {\n id: \"13\",\n title: \"architecture.md\",\n category: \"docs\",\n subtitle: \"Markdown File\",\n },\n];\n\nconst fluidSpring: Transition = {\n type: \"spring\",\n stiffness: 170,\n damping: 24,\n mass: 1.0,\n};\n\nconst microSpring: Transition = {\n type: \"spring\",\n stiffness: 380,\n damping: 26,\n mass: 0.8,\n};\n\nconst instantTransition: Transition = { duration: 0 };\n\nconst MAX_WIDTH = 480;\nconst BAR_HEIGHT = 48;\nconst MIN_INPUT_WIDTH = 220;\n\nfunction AppsIcon() {\n return (\n \n \n \n \n \n \n );\n}\n\nfunction FolderIcon() {\n return (\n \n \n \n );\n}\n\nfunction LayersIcon() {\n return (\n \n \n \n \n \n );\n}\n\nfunction DocsIcon() {\n return (\n \n \n \n \n \n );\n}\n\nfunction SearchIcon() {\n return (\n \n \n \n \n );\n}\n\nconst FILTER_BUTTONS = [\n { id: \"apps\" as const, label: \"Applications\", icon: AppsIcon },\n { id: \"folders\" as const, label: \"Folders\", icon: FolderIcon },\n { id: \"layers\" as const, label: \"Workspaces\", icon: LayersIcon },\n { id: \"docs\" as const, label: \"Documents\", icon: DocsIcon },\n];\n\nexport const SpotlightSearch: React.FC = ({\n value: controlledValue,\n defaultValue = \"\",\n onChange,\n onSubmit,\n activeFilter: controlledFilter,\n onFilterChange,\n placeholder = \"Spotlight Search\",\n items = DEFAULT_ITEMS,\n showResults = true,\n className,\n disabled = false,\n}) => {\n const generatedId = useId();\n const filterId = `spotlight-gooey-${generatedId.replace(/:/g, \"\")}`;\n const inputId = useId();\n const listboxId = `${inputId}-results`;\n const inputRef = useRef(null);\n const containerRef = useRef(null);\n const reduceMotion = useReducedMotion();\n const [width, setWidth] = useState(MAX_WIDTH);\n\n const [isHovered, setIsHovered] = useState(false);\n const [isFocused, setIsFocused] = useState(false);\n const [hoveredButtonId, setHoveredButtonId] = useState(null);\n\n const isControlled = controlledValue !== undefined;\n const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);\n const query = isControlled ? controlledValue : uncontrolledValue;\n\n const isControlledFilter = controlledFilter !== undefined;\n const [uncontrolledFilter, setUncontrolledFilter] =\n useState(null);\n const currentFilter = isControlledFilter\n ? controlledFilter\n : uncontrolledFilter;\n\n const [highlightedIndex, setHighlightedIndex] = useState(0);\n\n const isExpanded = isHovered || isFocused || query.length > 0;\n\n const isCompact = width < MAX_WIDTH;\n const buttonSize = isCompact ? 40 : BAR_HEIGHT;\n const buttonGap = isCompact ? 6 : 10;\n const buttonStep = buttonSize + buttonGap;\n const buttonOffsetY = (BAR_HEIGHT - buttonSize) / 2;\n const stackedFilters =\n width - FILTER_BUTTONS.length * buttonStep < MIN_INPUT_WIDTH;\n const expandedWidth = stackedFilters\n ? width\n : width - FILTER_BUTTONS.length * buttonStep;\n const filterOffsetX = (index: number) =>\n stackedFilters\n ? index * buttonStep\n : expandedWidth + buttonGap + index * buttonStep;\n const layoutTransition = reduceMotion ? instantTransition : fluidSpring;\n\n useEffect(() => {\n const container = containerRef.current;\n if (!container) return;\n const measure = () => setWidth(Math.min(MAX_WIDTH, container.clientWidth));\n measure();\n const observer = new ResizeObserver(measure);\n observer.observe(container);\n return () => observer.disconnect();\n }, []);\n\n const filteredItems = useMemo(() => {\n return items.filter((item) => {\n const matchesFilter = !currentFilter || item.category === currentFilter;\n const clean = query.trim().toLowerCase();\n if (!clean) return matchesFilter;\n const matchesQuery =\n item.title.toLowerCase().includes(clean) ||\n (item.subtitle && item.subtitle.toLowerCase().includes(clean));\n return matchesFilter && matchesQuery;\n });\n }, [items, currentFilter, query]);\n\n const safeHighlightedIndex =\n filteredItems.length > 0\n ? Math.min(Math.max(0, highlightedIndex), filteredItems.length - 1)\n : 0;\n\n const isResultsOpen =\n showResults && isFocused && (query.trim().length > 0 || !!currentFilter);\n const hasOptions = isResultsOpen && filteredItems.length > 0;\n const activeOptionId = hasOptions\n ? `${inputId}-option-${filteredItems[safeHighlightedIndex].id}`\n : undefined;\n\n const handleInputChange = (e: React.ChangeEvent) => {\n const val = e.target.value;\n if (!isControlled) {\n setUncontrolledValue(val);\n }\n setHighlightedIndex(0);\n onChange?.(val);\n };\n\n const handleFilterToggle = (filterIdSelected: SpotlightFilterId) => {\n const nextFilter =\n currentFilter === filterIdSelected ? null : filterIdSelected;\n if (!isControlledFilter) {\n setUncontrolledFilter(nextFilter);\n }\n setHighlightedIndex(0);\n onFilterChange?.(nextFilter);\n inputRef.current?.focus();\n };\n\n const handleKeyDown = (e: React.KeyboardEvent) => {\n if (e.key === \"Escape\") {\n if (query) {\n if (!isControlled) setUncontrolledValue(\"\");\n onChange?.(\"\");\n } else {\n inputRef.current?.blur();\n }\n } else if (e.key === \"ArrowDown\") {\n e.preventDefault();\n setHighlightedIndex((prev) =>\n filteredItems.length ? (prev + 1) % filteredItems.length : 0,\n );\n } else if (e.key === \"ArrowUp\") {\n e.preventDefault();\n setHighlightedIndex((prev) =>\n filteredItems.length\n ? (prev - 1 + filteredItems.length) % filteredItems.length\n : 0,\n );\n } else if (e.key === \"Enter\") {\n e.preventDefault();\n const selected = filteredItems[safeHighlightedIndex];\n if (selected) {\n onSubmit?.(selected.title, currentFilter);\n } else {\n onSubmit?.(query, currentFilter);\n }\n }\n };\n\n const dynamicPlaceholder = useMemo(() => {\n if (!currentFilter) return placeholder;\n switch (currentFilter) {\n case \"apps\":\n return \"Search Applications...\";\n case \"folders\":\n return \"Search Folders...\";\n case \"layers\":\n return \"Search Workspaces...\";\n case \"docs\":\n return \"Search Documents...\";\n default:\n return placeholder;\n }\n }, [currentFilter, placeholder]);\n\n return (\n setIsHovered(true)}\n onMouseLeave={() => {\n setIsHovered(false);\n setHoveredButtonId(null);\n }}\n onFocus={() => setIsFocused(true)}\n onBlur={(e) => {\n if (!e.currentTarget.contains(e.relatedTarget)) setIsFocused(false);\n }}\n className={cn(\n \"relative flex flex-col items-center select-none\",\n disabled && \"opacity-50 pointer-events-none\",\n className,\n )}\n style={{ width: MAX_WIDTH, maxWidth: \"100%\" }}\n >\n \n \n \n \n \n \n \n \n\n \n \n \n\n {FILTER_BUTTONS.map((btn, idx) => (\n \n ))}\n