Search Autocomplete
Provides autocomplete functionality for any form input field on a Drupal site, with suggestion sources from Views or custom callbacks.
search_autocomplete
Install
composer require 'drupal/search_autocomplete:^4.0'
composer require 'drupal/search_autocomplete:^3.0'
composer require 'drupal/search_autocomplete:^2.0'
Overview
Search Autocomplete is a powerful module that adds autocomplete functionality to virtually any input field on your Drupal site. During user input, the field expands to display a dropdown list of suggestions before form submission.
Suggestions can be sourced from Views using any entity type available on your site, or from custom PHP callbacks or external APIs. The module provides deep integration with Drupal core's Search module and Search Block out of the box.
Key capabilities include configurable minimum character triggers, maximum suggestion limits, auto-submit and auto-redirect behaviors, customizable "no results" and "more results" messages, and multiple CSS themes for styling the suggestion dropdown. Security is ensured through DOMPurify integration for XSS prevention.
Basic scenarios can be configured entirely through the UI, such as autocompleting Views exposed filters. Advanced users can create complex scenarios with custom code to integrate external data sources like Twitter, Google Places, or any API.
Features
- Add autocomplete suggestions to any input field using CSS selectors
- Use Views as suggestion data sources with custom display, style, and row plugins
- Support for custom callback URLs (internal Drupal paths or external APIs)
- Auto-submit form when a suggestion is selected
- Auto-redirect to suggestion link when selected
- Configurable minimum characters before autocomplete triggers
- Configurable maximum number of suggestions displayed
- Custom 'no results' message with configurable label, value, and redirect link
- Custom 'view all results' message with configurable label, value, and redirect link
- Multiple CSS themes (basic, minimal) with support for custom themes
- Admin helper tool that detects CSS selectors by hovering over input fields
- XSS protection via DOMPurify library integration
- Pre-configured autocomplete for Drupal core Search Block and Search Form
- Support for multi-value comma-separated fields
- Grouping of suggestions by category in Views
- Token support in messages: [search-phrase] and [search-count]
- Access control flags to protect configurations from editing or deletion
Use Cases
Autocomplete Search Block
Enable autocomplete on the core Drupal Search Block to suggest matching content titles as users type. The default configuration searches published nodes and displays up to 10 suggestions. Selecting a suggestion submits the search form with that value.
Autocomplete Views Exposed Filters
Add autocomplete to any Views exposed filter input field. Create a new configuration, use the admin helper tool to identify the filter's CSS selector, and specify a View display as the suggestion source. Users can filter content with autocomplete assistance.
User Search with Autocomplete
Enable autocomplete on user search forms to suggest matching usernames. The module includes a default configuration for the Search Form users tab that queries the users View callback.
External API Integration
Create autocomplete suggestions from external APIs like Google Places or custom web services. Configure the source field with the external API URL. The API must return JSON in the expected format with label, value, and optional link fields.
Custom Callback for Complex Suggestions
Build a custom Drupal controller that returns JSON suggestions from complex queries or aggregated data sources. Specify the controller's path as the source URL and return data in the expected format.
Grouped Suggestions by Category
Use Views grouping to organize suggestions by content type, taxonomy term, or other criteria. The style plugin supports grouping with visual separation between groups in the dropdown.
Multiple Autocomplete Fields on One Page
Configure multiple autocomplete configurations with different CSS selectors to enable autocomplete on multiple fields simultaneously. Each can have its own source, theme, and behavior settings.
Tips
- Use the admin helper tool to easily identify CSS selectors by hovering over input fields
- Create custom CSS themes by copying an existing file in css/themes/ and modifying it
- Use the [search-phrase] token in no-result and more-results messages to show users what they searched for
- Set minimum characters to 2-3 to reduce server load while still providing useful suggestions
- Use View grouping to categorize suggestions visually (e.g., by content type)
- For exposed filter autocomplete, the View's exposed filter identifier is automatically passed to the callback
- Test autocomplete behavior in the View preview - JSON output is formatted for readability
Technical Details
Admin Pages 4
/admin/config/search/search_autocomplete
Main administration page displaying a list of all autocompletion configurations. Allows enabling/disabling individual configurations and toggling the admin helper tool. Shows configuration name, enabled status, and CSS selector for each entry.
/admin/config/search/search_autocomplete/add
Form for creating a new autocompletion configuration. Requires a human-readable name, machine name, and CSS selector for the target input field.
/admin/config/search/search_autocomplete/manage/{autocompletion_configuration}
Comprehensive form for configuring all aspects of an autocompletion configuration including display behavior, data source, and theme.
/admin/config/search/search_autocomplete/manage/{autocompletion_configuration}/delete
Confirmation form for deleting an autocompletion configuration. Some default configurations may have deletion disabled.
Permissions 2
Hooks 5
hook_element_info_alter
Alters form elements to add custom autocomplete processing. Identifies elements with processAutocomplete and adds process_search_autocomplete handler.
hook_library_info_build
Dynamically creates library definitions for CSS theme files found in the css/themes directory.
hook_library_info_alter
Modifies core/drupal.autocomplete library to inject custom JavaScript and add DOMPurify dependency if available.
hook_page_attachments
Attaches autocomplete configurations to pages. Loads settings for all enabled configurations with CSS selectors and attaches admin helper library if enabled.
hook_form_alter
Applies default autocomplete configurations to Drupal core search forms (search_block_form and search_form).
Troubleshooting 5
Verify the CSS selector is correct using browser developer tools. Ensure the user has 'use search autocomplete' permission. Clear all caches after configuration changes. Check that the configuration is enabled.
Download DOMPurify from https://github.com/cure53/DOMPurify and place it in libraries/dompurify/ so the path libraries/dompurify/dist/purify.min.js exists. Alternatively, configure Composer to download it automatically.
Check the browser console for JavaScript errors. Verify the source URL or View display exists and is accessible. Ensure the View has an Autocompletion Callback display properly configured.
Enable the admin helper checkbox on the main configuration page. Ensure you have 'administer search autocomplete' permission. The tool only appears on text and search input fields.
Some default configurations have the editable or deletable flag set to FALSE for protection. These settings are stored in config and cannot be changed through the UI.
Security Notes 5
- The module requires DOMPurify library for XSS protection - do not use without it
- Suggestion output is sanitized through DOMPurify before rendering in the dropdown
- The 'use search autocomplete' permission controls which users see autocomplete functionality
- External callback URLs should be carefully vetted to prevent data exposure
- Configuration entities have editable/deletable flags to prevent accidental modification of critical configurations