Entity Browser

Provides a generic, highly extensible entity browser/picker/selector that can be used in any context where selecting entities is needed.

entity_browser
100,889 sites
172
drupal.org
gui api field
media entity-reference file-upload content-authoring entity-selection modal iframe views-integration field-widget plugin-architecture
Drupal 10 Drupal 11

Install

Drupal 11, 10 v8.x-2.15
composer require 'drupal/entity_browser:8.x-2.15'

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.

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

Technical Details

Admin Pages 3
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 2
Administer entity browsers

Create and modify entity browsers for generating browsing, creating and selecting entities. This permission is restricted.

Access [Browser Name] pages

Dynamically generated permission for each entity browser that uses a route (Modal, iFrame, Standalone). Allows access to the entity browser pages.

Hooks 9
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 6
Entity browser modal not opening

Ensure the Drupal AJAX dialog library is loaded. Check browser console for JavaScript errors. Verify the entity browser has a valid configuration.

View widget shows 'Entity browser select form field not found'

Add the 'Entity browser select form' field to your View. This field must be present for selection to work.

Selected entities not appearing in the field

Check cardinality settings. If using 'Edit selection' mode, ensure the selection display plugin supports preselection (use Multi step display, not No display).

File uploads fail or show wrong extensions

Verify the 'Allowed file extensions' setting in the upload widget matches your requirements. Check PHP upload limits.

Bundle filter not working in Views

The entity_browser_bundle filter gets values from widget context. Ensure your field widget passes target_bundles in widget_context.

Entity browser opens but is empty

Check user permissions for 'access [browser_id] entity browser pages'. Verify the View has results and the display type is 'Entity browser'.

Security Notes 4
  • 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