Search API Autocomplete
Adds autocomplete functionality to Search API searches, allowing users to see search suggestions as they type.
search_api_autocomplete
Install
composer require 'drupal/search_api_autocomplete:8.x-1.11'
composer require 'drupal/search_api_autocomplete:8.x-1.9'
Overview
Search API Autocomplete adds autocomplete capabilities to Search API searches. As users type in search fields, they receive real-time suggestions based on indexed data, previous searches, or live search results.
The module provides fine-grained control over autocompletion behavior, allowing administrators to enable and configure autocomplete for each search individually. This includes search views created with Views module and search pages created with Search API Pages module.
Multiple suggestion methods (suggesters) can be configured per search, including server-based suggestions from indexed data, live result displays showing actual search results as the user types, and custom script integration for advanced use cases. Each suggester can be weighted and limited independently.
Per-search permissions ensure appropriate access control, and comprehensive configuration options allow customization of suggestion limits, input delays, minimum character requirements, result count display, and auto-submit behavior.
Features
- Autocomplete for Search API Views exposed form fulltext fields
- Autocomplete for Search API Pages search forms
- Multiple suggester plugins: Server-based suggestions, Live Results, Custom Script
- Per-search configuration with individual enable/disable controls
- Configurable maximum suggestions limit per search
- Minimum input length requirement before showing suggestions
- Adjustable delay between keystrokes and suggestion requests
- Optional display of estimated result counts for each suggestion
- Auto-submit functionality when suggestion is selected
- Per-suggester weight ordering and result limits
- Per-search permission control for fine-grained access
- Support for transliteration in autocomplete matching
- Live Results suggester with configurable view modes per entity bundle
- Live Results highlighting using Search API Highlight processor
- Custom Script suggester for performance-optimized external endpoints
- Extensible plugin architecture for custom suggesters and search types
Use Cases
Basic Search Autocomplete for Views
Enable autocomplete on a Search API View's exposed fulltext filter. Navigate to the index's Autocomplete tab, enable the View's search, select 'Retrieve from server' suggester, and save. Users will see keyword suggestions as they type based on indexed content.
Live Results Preview
Show actual search results as users type. Configure the 'Display live results' suggester and optionally select view modes for each content type. Users see clickable result links with entity labels or rendered view mode content as they type.
Combined Suggestions Strategy
Enable multiple suggesters with different weights. For example, use 'Retrieve from server' (weight -10) for keyword suggestions and 'Display live results' (weight 0) for result previews. Set per-suggester limits to show 5 keyword suggestions and 3 live results.
High-Performance Custom Autocomplete
For high-traffic sites, enable enable_custom_scripts setting and configure the 'Use custom script' suggester pointing to a lightweight PHP endpoint that queries the search server directly, bypassing Drupal bootstrap for faster response times.
Search Page Autocomplete
Add autocomplete to Search API Pages search blocks. After enabling the module, autocomplete is automatically available on Search API Pages. Configure through the associated index's Autocomplete tab.
Field-Specific Autocomplete
Restrict autocomplete suggestions to specific indexed fields. In suggester configuration, select 'Override used fields' and choose only the fields that should be searched for generating suggestions (e.g., only title field, not body).
Tips
- Use Search API Solr Autocomplete module when using Solr backend for improved autocomplete functionality with term completion and spellcheck integration
- Set per-suggester limits when using multiple suggesters to ensure a good mix of suggestion types
- The 'Display live results' suggester works best when the backend supports partial matching or when used with the Highlight processor
- For Views with multiple fulltext filters, autocomplete is added to all fields identified as fulltext fields
- Test autocomplete with different user roles to ensure permissions are correctly configured
- Consider the 'Suggest result labels as keywords' option in Live Results when you want users to refine their search rather than jump directly to results
- The delay setting balances user experience against server load - 300ms is a good default, increase for high-traffic sites
Technical Details
Admin Pages 2
/admin/config/search/search-api/index/{index}/autocomplete
Overview page for managing autocomplete configuration for all searches associated with a Search API index. Lists all available searches (Views, Pages) grouped by type, with checkboxes to enable/disable autocomplete for each. Provides links to edit individual search configurations or delete existing configurations.
/admin/config/search/search-api/index/{index}/autocomplete/{search}/edit
Detailed configuration form for an individual autocomplete search. Allows selection and configuration of suggester plugins, setting autocomplete behavior options, and search plugin-specific settings.
Permissions 2
Hooks 4
hook_search_api_autocomplete_suggestions_alter
Alter the suggestions that will be returned for an autocomplete request. Allows modules to add, remove, or modify suggestions before they are sent to the client.
hook_search_api_autocomplete_suggester_info_alter
Alter the available suggester plugin definitions. Allows overriding plugin class, label, description, or other properties.
hook_search_api_autocomplete_search_info_alter
Alter the available search plugin definitions. Allows overriding plugin class or other properties for search plugins.
hook_search_api_autocomplete_views_fulltext_fields_alter
Alter which Views fields are considered fulltext fields for autocomplete. Autocomplete will be added to text inputs for these fields.
Troubleshooting 6
Verify: 1) Autocomplete is enabled for the search in index Autocomplete tab, 2) User has 'Use autocomplete for X' permission, 3) At least one suggester is enabled and configured, 4) For 'Retrieve from server' suggester, ensure backend supports search_api_autocomplete feature, 5) Check browser console for JavaScript errors.
The search server's backend must support the 'search_api_autocomplete' feature. Check Search API documentation for backend feature support. Consider using 'Display live results' suggester as an alternative.
Increase the 'Delay' setting to reduce request frequency (e.g., 500ms). Consider using per-suggester limits. For high-traffic sites, implement a custom script suggester that bypasses Drupal.
Check which fields are being searched. In suggester settings, use 'Override used fields' to explicitly select the fields that should be searched. Ensure the index is up to date and contains the expected content.
The Live Results suggester respects item access. Ensure the search index has appropriate access checking configured. Items the user cannot access are filtered from suggestions.
Enable the hidden suggester by setting search_api_autocomplete.settings:enable_custom_scripts to TRUE via drush config:set or editing the config YAML directly.
Security Notes 5
- Each autocomplete search has its own permission - review and assign these permissions carefully to appropriate roles
- The 'Use custom script' suggester bypasses normal Drupal access checking - only enable if you understand the security implications
- Custom script endpoints should implement their own access control and input validation
- The autocomplete endpoint returns JSON with unsanitized values in the 'value' key - always escape before rendering as HTML
- Result counts may reveal information about content existence - consider disabling show_count for sensitive searches