Contextual Search

AI
Adaptive

AI-powered search with smart suggestions based on user context and history. Features recent searches, AI recommendations with explanations, and keyboard shortcuts.

Preview

Search with AI suggestions and recent history

Recent
AI Suggestions

Custom Configuration

Custom suggestions, placeholder, and history

Recent
AI Suggestions

Initially Closed

Suggestions appear on focus

Props

ContextualSearch component API reference

PropTypeDefaultDescription
placeholderstring'Search anything...'Placeholder text for the search input
recentSearchesstring[](default searches)Array of recent search strings
aiSuggestionsAISuggestion[](default suggestions)Array of AI-powered suggestions
defaultOpenbooleantrueInitial open state for suggestions panel
onSearch(query: string) => voidCallback when search is submitted (Enter key)
onRecentClick(search: string) => voidCallback when a recent search chip is clicked
onSuggestionClick(suggestion: AISuggestion) => voidCallback when an AI suggestion is clicked
onClearRecent() => voidCallback when "Clear all" is clicked
classNamestringAdditional CSS classes for the container

AISuggestion Type

PropTypeDefaultDescription
text*stringSuggestion text to display
reason*stringContextual reason why this is suggested

Usage

Import and implementation example

import { ContextualSearch } from '@/components/ui/contextual-search'

export default function Example() {
  const handleSearch = (query: string) => {
    // Perform search
    console.log('Searching for:', query)
  }

  const handleSuggestionClick = (suggestion: { text: string; reason: string }) => {
    // Use the suggestion
    console.log('Selected:', suggestion.text)
  }

  return (
    <>
      {/* With defaults */}
      <ContextualSearch onSearch={handleSearch} />

      {/* Custom configuration */}
      <ContextualSearch
        placeholder="Search projects, tasks, people..."
        recentSearches={['project A', 'team B', 'budget C']}
        aiSuggestions={[
          {
            text: 'Tasks due this week',
            reason: 'Based on your current focus'
          },
          {
            text: 'Team performance',
            reason: 'You check this every Monday'
          }
        ]}
        onSearch={handleSearch}
        onRecentClick={(search) => setQuery(search)}
        onSuggestionClick={handleSuggestionClick}
        onClearRecent={() => clearHistory()}
      />

      {/* Initially closed */}
      <ContextualSearch defaultOpen={false} />
    </>
  )
}
This block is self-contained (no UI component dependencies)

Features

Built-in functionality

  • AI-powered suggestions: Smart recommendations with contextual reasons
  • Recent search history: Quick access to previous searches as chips
  • Keyboard shortcut hint: Visual ⌘K indicator for quick access
  • AI badge indicator: Shows search is AI-enhanced with violet badge
  • Clear all functionality: Easy management of search history
  • Auto-open on focus: Suggestions appear when input is focused
  • Gradient suggestion cards: Indigo-to-white gradient for AI suggestions
  • Enter to search: Submit search query with Enter key
  • Dark mode: Full dark mode support

Accessibility

Accessibility considerations

ARIA Attributes

Search input is a native input elementRecent search chips are native buttonsAI suggestion cards are native buttonsClear all is a native button

Keyboard Navigation

KeyAction
TabNavigate between input, recent searches, and suggestions
EnterSubmit search query when input is focused
Enter / SpaceSelect a suggestion or recent search

Notes

  • Input auto-focuses and opens suggestions panel
  • Recent searches section has clear section label
  • AI suggestions section has Sparkles icon label
  • Each suggestion shows reason for recommendation
  • Consider adding aria-live for dynamic suggestion updates