Configuration - FlowSearch Documentation

Basic Configuration

Every FlowSearch instance requires at minimum the API URL and API key:

const flowSearch = new FlowSearch({
  // Required
  apiUrl: 'https://api.flowsearch.io',
  apiKey: 'YOUR_API_KEY'
});

All Configuration Options

Core Settings

Option	Type	Default	Description
`apiUrl`	string	required	FlowSearch API endpoint URL
`apiKey`	string	required	Your FlowSearch API key
`debug`	boolean	false	Enable debug logging to console

Element Selectors

Option	Default	Description
`searchInputSelector`	'[data-flowsearch-input]'	CSS selector for search input
`resultsContainerSelector`	'[data-flowsearch-results]'	CSS selector for results container
`submitButtonSelector`	'[data-flowsearch-submit]'	CSS selector for submit button

Search Behavior

const flowSearch = new FlowSearch({
  apiUrl: 'https://api.flowsearch.io',
  apiKey: 'YOUR_API_KEY',
  
  // Search timing
  debounceMs: 300,           // Wait 300ms after typing stops
  minQueryLength: 2,         // Minimum characters to trigger search
  
  // Results
  maxResults: 10,            // Max results in dropdown
  maxPageResults: 20,        // Max results per page (search page)
  
  // Features
  enableRealTimeSearch: true,     // Search as user types
  enableKeyboardNavigation: true, // Arrow key navigation
  enableCaching: true,            // Cache search results
  cacheTimeout: 300000            // Cache expires in 5 minutes
});

UI Options

const flowSearch = new FlowSearch({
  apiUrl: 'https://api.flowsearch.io',
  apiKey: 'YOUR_API_KEY',
  
  // Display
  showLoadingIndicator: true,  // Show spinner during search
  showSearchStats: true,       // Show "X results in Yms"
  showPagination: true,        // Show pagination controls
  
  // Behavior
  autoFocus: false,            // Auto-focus input on page load
  clearOnEscape: true,         // Clear search on Escape key
  
  // Dropdown
  autoShowDropdown: true,      // Show dropdown when typing
  hideOnOutsideClick: true,    // Hide when clicking outside
  dropdownMaxHeight: '400px',  // Maximum dropdown height
  dropdownPosition: 'bottom'   // 'bottom', 'top', or 'auto'
});

Search Parameters

Fine-tune how search queries are processed:

const flowSearch = new FlowSearch({
  apiUrl: 'https://api.flowsearch.io',
  apiKey: 'YOUR_API_KEY',
  
  searchParameters: {
    // Fields to search
    queryFields: ['title', 'content', 'description'],
    
    // Sorting
    sortBy: 'relevance',        // 'relevance', 'date', 'title'
    sortOrder: 'desc',
    
    // Typo tolerance
    typoTolerance: true,
    
    // Highlighting
    highlightFields: ['title', 'content'],
    highlightStartTag: '<mark>',
    highlightEndTag: '</mark>',
    
    // Faceting (filters)
    facetBy: ['category', 'author', 'tags'],
    
    // Pre-defined filters
    filters: {
      category: 'blog',
      status: 'published'
    }
  }
});

Custom Templates

Customize how search results are rendered:

const flowSearch = new FlowSearch({
  apiUrl: 'https://api.flowsearch.io',
  apiKey: 'YOUR_API_KEY',
  
  templates: {
    // Dropdown result item
    dropdownHit: `
      <div class="search-result">
        <h3 class="result-title">{{title}}</h3>
        <p class="result-description">{{description}}</p>
        <span class="result-category">{{category}}</span>
      </div>
    `,
    
    // Empty state
    dropdownEmpty: '<div class="no-results">No results found</div>',
    
    // Loading state
    dropdownLoading: '<div class="loading">Searching...</div>',
    
    // Error state
    dropdownError: '<div class="error">Search unavailable</div>',
    
    // Stats template
    stats: 'Found {{nbHits}} results in {{processingTimeMS}}ms'
  }
});

Event Callbacks

Handle search events with custom callbacks:

const flowSearch = new FlowSearch({
  apiUrl: 'https://api.flowsearch.io',
  apiKey: 'YOUR_API_KEY',
  
  callbacks: {
    // Search lifecycle
    onSearchStart: (query, state) => {
      console.log('Searching for:', query);
    },
    
    onSearchComplete: (results, state) => {
      console.log('Found', results.nbHits, 'results');
    },
    
    onSearchError: (error, state) => {
      console.error('Search failed:', error);
    },
    
    // User interactions
    onResultClick: (result, event) => {
      // Track analytics
      gtag('event', 'search_click', {
        search_term: result.query,
        result_title: result.title
      });
    },
    
    // Initialization
    onInit: (instance) => {
      console.log('FlowSearch ready!');
    }
  }
});

Analytics Configuration

const flowSearch = new FlowSearch({
  apiUrl: 'https://api.flowsearch.io',
  apiKey: 'YOUR_API_KEY',
  
  // Enable built-in analytics
  enableAnalytics: true,
  
  analytics: {
    // Track these events
    trackEvents: {
      search: true,        // Track searches
      click: true,         // Track result clicks
      noResults: true,     // Track zero-result searches
      pagination: true     // Track page changes
    },
    
    // Custom event handler (send to your analytics)
    onEvent: (eventType, eventData) => {
      gtag('event', eventType, eventData);
    }
  }
});

Error Handling

const flowSearch = new FlowSearch({
  apiUrl: 'https://api.flowsearch.io',
  apiKey: 'YOUR_API_KEY',
  
  errorHandling: {
    // Show user-friendly error messages
    showErrorMessages: true,
    
    // Gracefully degrade on failure
    gracefulDegradation: true,
    
    // Fallback to native form submission
    fallbackBehavior: 'native-search',
    
    // Retry configuration
    retryAttempts: 3,
    retryDelay: 1000,
    
    // Request timeout (ms)
    requestTimeout: 5000,
    
    // Custom error handler
    onError: (error, context) => {
      // Log to your error tracking service
      Sentry.captureException(error);
    }
  }
});

Runtime Configuration Updates

Update configuration after initialization:

// Update general config
flowSearch.updateConfig({
  debounceMs: 500,
  maxResults: 15
});

// Update templates
flowSearch.updateTemplates({
  dropdownHit: newTemplate
});

// Update search parameters
flowSearch.updateSearchParameters({
  sortBy: 'date:desc'
});

Configuration Reference