Entity Browser
entity_browser
Provides a generic, highly extensible entity browser/picker/selector that can be used in any context where selecting entities is needed.
Overview
Entity Browser is a comprehensive module that provides a standardized and highly customizable interface for browsing, creating, and selecting entities in Drupal. It offers a flexible plugin-based architecture with multiple display options (modal, iframe, standalone), various widget types for entity selection (Views, file upload, media image upload), and customizable selection displays.
The module integrates seamlessly with entity reference fields, providing specialized field widgets that enhance the entity selection experience. It features support for multi-step selection workflows, drag-and-drop reordering, cardinality validation, and contextual bundle filtering. Entity Browser is particularly useful for media management, content editing workflows, and any scenario requiring sophisticated entity selection capabilities.
Built with extensibility in mind, developers can create custom plugins for displays, widgets, widget selectors, selection displays, field widget displays, and validation. The module also provides a comprehensive event system for customizing behavior at various stages of the selection process.
Install
composer require 'drupal/entity_browser:8.x-2.15'
Features
- Configurable entity browser instances with customizable labels and machine names
- Multiple display plugins: Modal dialog, iFrame embedded, and Standalone page
- Widget plugins for entity selection: Views-based selection, file upload, and media image upload
- Widget selector plugins: Tabs and dropdown for navigating between multiple widgets
- Selection display plugins: Multi-step display with work-in-progress selection zone, and no display for immediate selection
- Field widget display plugins: Entity label, image thumbnail, and rendered entity displays
- Entity reference field widget with edit, remove, and replace buttons
- File/Image field widget with metadata editing (alt, title, description)
- Cardinality validation and entity type validation
- Drag-and-drop reordering of selected entities
- Views integration with custom display plugin and selection form field
- Contextual bundle filtering in Views
- Support for preselection in edit mode
- Event-driven architecture for customization
- JavaScript callbacks for AJAX-based entity selection
- Token support for upload locations
- Integration with Inline Entity Form module for creating entities within the browser
Use Cases
Media Library Alternative
Create a custom media browser with Views-based media listing, upload widget for new media, and thumbnail previews. Use modal display for seamless content editing workflow.
Content Reference Field
Replace the default entity reference autocomplete with a visual entity browser. Configure a View showing content with images and use 'rendered_entity' display for rich previews.
Image Field with Gallery Selection
Use entity browser with file/image field widget. Configure multi-step selection display for reviewing selections before confirming. Enable drag-and-drop reordering.
Inline Entity Creation
Enable entity_browser_entity_form submodule and add 'Entity form' widget alongside View widget. Users can either select existing entities or create new ones without leaving the browser.
Contextual Entity Selection
Use the entity_browser_bundle filter and entity_browser_widget_context argument default to show only entities matching the field's target bundle configuration.
WYSIWYG Entity Embedding
Integrate with Entity Embed module to allow editors to browse and embed entities (media, nodes) directly from the WYSIWYG editor using entity browser.
Tips
- Use the 'Auto select' option on View widgets for single-click selection without needing to press a submit button
- Enable 'Selection hidden by default' in multi-step display for cleaner UI when selection area is not immediately needed
- Use the 'Replace' button option for single-value fields to allow quick replacement without manual remove-then-add workflow
- Leverage hook_entity_browser_view_executable_alter to pass contextual arguments to Views based on the current page
- Use different entity browsers for different use cases rather than one complex browser
- Test with entity_browser_example module enabled to see working configurations
- For better performance with large entity sets, use AJAX-enabled Views with pagination
- Consider cardinality when choosing between checkboxes and radios - the view widget auto-switches based on cardinality
Dependencies
Related Projects
Deep integration with Views module. Provides custom 'Entity browser' display plugin, 'Entity browser select form' field, contextual bundle filter, and widget context argument default plugin.
The entity_browser_entity_form submodule provides an 'Entity form' widget for creating entities inline within the entity browser.
Integration with Entity Embed for embedding entities in WYSIWYG editors. Passes contextual information (embed button ID, entity type, bundles) to entity browser.
Seamless integration with Drupal core Media module. The media_image_upload widget creates media entities from uploaded images.
When file_entity module is installed, file browser widget uses its view builder for rich file previews.
When token module is available, upload location fields support token replacement.
Admin Pages
| Title | Path | Description |
|---|---|---|
| Entity Browsers | /admin/config/content/entity_browser |
Lists all configured entity browsers. From here you can add new browsers, edit existing ones, configure widgets, or delete browsers. |
| Add Entity browser | /admin/config/content/entity_browser/add |
Creates a new entity browser configuration with display, widget selector, and selection display settings. |
| Widget Settings | /admin/config/content/entity_browser/{entity_browser}/widgets |
Configure widgets for the entity browser. Add, remove, and reorder widgets that provide different ways to select entities. |
Permissions
| Permission | Description |
|---|---|
|
Create and modify entity browsers for generating browsing, creating and selecting entities. This permission is restricted. |
|
Dynamically generated permission for each entity browser that uses a route (Modal, iFrame, Standalone). Allows access to the entity browser pages. |
Hooks
| Hook | Description |
|---|---|
hook_entity_browser_display_info_alter |
Alter the display plugin definitions |
hook_entity_browser_widget_info_alter |
Alter the widget plugin definitions |
hook_entity_browser_selection_display_info_alter |
Alter the selection display plugin definitions |
hook_entity_browser_widget_selector_info_alter |
Alter the widget selector plugin definitions |
hook_entity_browser_field_widget_display_info_alter |
Alter the field widget display plugin definitions |
hook_entity_browser_widget_validation_info_alter |
Alter the widget validation plugin definitions |
hook_form_entity_browser_form_alter |
Alter any entity browser form (base form ID alter) |
hook_form_entity_browser_ENTITY_BROWSER_ID_form_alter |
Alter a specific entity browser form by ID |
hook_entity_browser_view_executable_alter |
Alter the view executable in the view widget before rendering |
Troubleshooting
Ensure the Drupal AJAX dialog library is loaded. Check browser console for JavaScript errors. Verify the entity browser has a valid configuration.
Add the 'Entity browser select form' field to your View. This field must be present for selection to work.
Check cardinality settings. If using 'Edit selection' mode, ensure the selection display plugin supports preselection (use Multi step display, not No display).
Verify the 'Allowed file extensions' setting in the upload widget matches your requirements. Check PHP upload limits.
The entity_browser_bundle filter gets values from widget context. Ensure your field widget passes target_bundles in widget_context.
Check user permissions for 'access [browser_id] entity browser pages'. Verify the View has results and the display type is 'Entity browser'.
Security Notes
- The 'administer entity browsers' permission is restricted and should only be granted to trusted administrators
- Entity browser respects entity access - users can only select entities they have view access to
- File upload widgets inherit field-level validation for extensions and file size
- The edit button in field widgets checks entity update access before display