Select 2
Integrates the Select2 JavaScript library with Drupal, providing enhanced select form elements and field widgets for list fields and entity reference fields.
select2
Install
composer require 'drupal/select2:^2.0'
composer require 'drupal/select2:8.x-1.15'
composer require 'drupal/select2:8.x-1.13'
Overview
The Select2 module integrates the popular Select2 JavaScript library with Drupal, providing a modern, user-friendly alternative to standard HTML select elements. It offers rich features including searchable dropdowns, autocomplete functionality, and support for selecting multiple values with drag-and-drop reordering.
The module provides three main components: a render element (#type => 'select2') for custom forms, a field widget for list fields (list_integer, list_float, list_string), and an advanced field widget for entity reference fields. The entity reference widget supports AJAX-powered autocomplete for large datasets and can create new entities on-the-fly (autocreate feature).
Additionally, the module includes integration with the Better Exposed Filters module for Views exposed filters and provides two submodules: Select2 Facets for Search API facet widgets, and Select2 Publish for displaying publish status indicators on referenced entities. Theme integration is included for Drupal's core themes (Seven, Claro) and the popular Gin admin theme.
Features
- Provides a Select2 form render element (#type => 'select2') with support for single and multiple selection, option groups, and customizable Select2 JavaScript configuration
- Select2 field widget for list fields (list_integer, list_float, list_string) with configurable field width
- Advanced Select2 field widget for entity reference fields with AJAX autocomplete support for large datasets
- Entity autocreate functionality allowing new entities to be created on-the-fly during selection
- Drag-and-drop reordering of selected items in multiple selection mode using the Sortable library
- Internationalization (i18n) support with automatic language detection and loading of Select2 language files
- Theme integration with automatic CSS loading for Seven, Claro, and Gin admin themes
- Integration with Better Exposed Filters module providing Select2 widgets for Views exposed filters and sort options
- Custom autocomplete endpoint (/select2_autocomplete) with secure selection settings handling
- Extensible architecture with hooks for modifying autocomplete matches (hook_select2_autocomplete_matches_alter)
- Support for field cardinality limits (maximumSelectionLength) and the field_config_cardinality module
Use Cases
Improved entity reference selection for content editors
Replace standard entity reference autocomplete or select widgets with Select2 for a better user experience. Editors can search through large lists of entities with instant filtering, see more context in dropdown options, and reorder multiple selections via drag-and-drop. Enable autocomplete mode for entity reference fields with thousands of options to improve page load performance.
Taxonomy term selection with autocreate
Use Select2 for taxonomy term reference fields with autocreate enabled. Editors can select existing terms from the searchable dropdown or type new term names that will be automatically created when the content is saved. The comma separator allows quick entry of multiple new tags.
Enhanced Views exposed filters
When using the Better Exposed Filters module, replace standard select elements in Views exposed filters with Select2 widgets. This is particularly useful for Views with many filter options (e.g., filtering by taxonomy terms, authors, or content types) where the searchable dropdown significantly improves usability.
Search API faceted search
Use the Select2 Facets submodule to provide Select2 widgets for Search API facets. This is ideal for faceted search interfaces with many possible values, allowing users to quickly find and select the facet values they need. Enable autocomplete mode for facets with hundreds or thousands of values.
Custom form elements in modules
Developers can use the Select2 render element (#type => 'select2') in custom forms to provide enhanced select functionality. The element supports all standard Select2 configuration options via the #select2 property, allowing full customization of behavior and appearance.
Editorial workflow with publish status visibility
Enable the Select2 Publish submodule to show editors which referenced entities are published or unpublished directly in the Select2 dropdown. Unpublished entities appear in red, making it easy to identify draft content when creating relationships between entities.
Tips
- Enable autocomplete mode for entity reference fields with more than 50-100 options to improve page load performance
- Use the 'STARTS_WITH' match operator instead of 'CONTAINS' for large datasets to improve autocomplete performance
- Set an appropriate match_limit (e.g., 10-20) to prevent overwhelming users with too many autocomplete suggestions
- Create a custom Select2 theme CSS file in your admin theme to match your site's design - copy styles with '--default' from select2.css and replace with your theme's machine name
- Use the #select2 property on the render element to override any Select2 JavaScript configuration option
- The module emits a 'select2-init' jQuery event before initialization, allowing other modules to modify the configuration
- For very large entity reference fields, consider using Views-based selection handlers with appropriate filters to limit the available options
- The comma separator is automatically enabled for autocreate fields, allowing quick entry of multiple new items
Technical Details
Hooks 1
hook_select2_autocomplete_matches_alter
Allows modules to alter the autocomplete matches returned by the Select2 autocomplete endpoint. This hook is invoked after entities are matched but before the results are returned to the client.
Troubleshooting 6
Download the Select2 library from https://github.com/select2/select2/releases and place it in the libraries folder (libraries/select2). The library should contain dist/js/select2.min.js and dist/css/select2.min.css files. Alternatively, use Composer with asset-packagist to manage the library automatically.
Ensure the Select2 JavaScript library is correctly installed and accessible. Check browser console for JavaScript errors. Verify that jQuery and other dependencies are loading correctly. Clear Drupal caches and browser cache.
Verify that the target entity type and bundle settings are correctly configured in the field settings. Check that the user has permission to view the referenced entities. Ensure the selection handler settings (match_operator, match_limit) are appropriate for your use case.
Ensure autocreate is enabled in the field settings (handler_settings). Verify that auto_create_bundle is set to a valid bundle, or there is only one target bundle configured. Check that the current user has permission to create entities of the target type.
The module automatically loads theme-specific CSS for Seven, Claro, and Gin themes. For custom themes, create a select2.theme library in your theme's libraries.yml file with custom CSS. See the module README for instructions on creating custom Select2 themes.
Ensure the Sortable library (core/sortable) is loading correctly. This is a core Drupal library that should be available by default. Check browser console for JavaScript errors related to Sortable.
Security Notes 3
- The module uses secure hash-based selection settings keys to prevent tampering with autocomplete endpoint parameters
- Autocomplete results respect entity access permissions - users can only see entities they have permission to view
- Selection settings are stored in Drupal's key/value store and validated using HMAC with the site's hash salt