File Entity Browser
Provides a beautiful, modern media library experience for Drupal using Masonry grid layout and DropzoneJS upload, built on Entity Browser and Entity Embed APIs.
file_browser
Install
composer require 'drupal/file_browser:^2.0'
Overview
The File Entity Browser module provides an intuitive file browsing experience for Drupal content editors. It displays files in a responsive, grid-based Masonry layout, making it easy to browse, upload, and select images and other files.
The primary goal is to bring back the user-friendly experience of the Drupal 7 Media Library while leveraging modern Drupal APIs including Entity Browser and Entity Embed. The module integrates DropzoneJS for drag-and-drop file uploads and uses Backbone.js for smart item selection with cardinality support.
It provides pre-configured entity browsers that work out-of-the-box with both iframe and modal display modes, along with custom image styles optimized for the browser interface.
Features
- Responsive Masonry grid layout for browsing files with automatic image loading detection
- DropzoneJS integration for drag-and-drop file uploads with supported file type validation
- Pre-configured Entity Browsers with iframe (100% width, 768px height) and modal (1100x650px) display modes
- Smart file selection with Backbone.js supporting single and multi-select based on field cardinality
- Custom Views field plugin for rendering file previews with thumbnail display
- Image Embed block for placing multiple images with alt text and ordering support
- Field widget compatible with File and Image field types
- Preview modal with image style selection for viewing files in different sizes
- Multi-step selection display showing thumbnails of selected files
- Integration with Libraries module for flexible library path management
- Example submodule providing ready-to-use content type and block type configurations
Use Cases
Media-rich content editing
Content editors can easily browse existing media files and upload new ones through a visual, grid-based interface when creating or editing nodes. The Masonry layout provides a modern, Pinterest-like browsing experience that scales from mobile to desktop.
Image embedding in WYSIWYG editor
Using the Entity Embed integration, editors can insert images directly into CKEditor text areas. The File Browser button in the editor toolbar opens a modal browser for selecting files, with preview support for different image styles.
Multi-image field selection
For fields requiring multiple images (galleries, slideshows), the selection interface tracks selected items with visual indicators, supports drag ordering, and enforces cardinality limits with visual feedback when the limit is reached.
Custom block image galleries
Site builders can use the Image Embed block plugin to create image gallery blocks with configurable image styles, alt text for accessibility, and drag-and-drop ordering of images.
Quick prototyping with example module
Developers can enable the File Browser Example submodule to immediately have a working content type and block type with File Browser fields configured, useful for demonstrations or as a starting point for custom implementations.
Tips
- Use Composer with the Wikimedia Composer Merge Plugin for automatic JavaScript library management by including composer.libraries.json in your merge-plugin configuration
- Enable the File Browser Example submodule for a quick demonstration of how to configure fields with File Browser
- The modal display (browse_files_modal) is recommended for most use cases as it doesn't require page reload and provides a cleaner user experience
- Double-click on a file in the browser to automatically select it and close the browser, useful for single-select fields
- The search field in the file browser uses debounced input (600ms delay) to prevent excessive filtering during typing
- For large file libraries, consider customizing the Views pager settings to balance performance with usability
Technical Details
Admin Pages 1
/admin/file-browser-preview/{file}/{image_style}
Displays a preview of a file in a modal dialog. For image files, allows selection of different image styles to preview the image at various sizes. Non-image files display a placeholder SVG.
Hooks 4
hook_form_alter
Attaches File Browser libraries and CSS classes to entity browser forms (browse_files and browse_files_modal forms)
hook_preprocess_details
Attaches iframe CSS library for file browser reference fields displayed in details elements
hook_library_info_alter
Integrates with Libraries module to dynamically resolve JavaScript library paths for Backbone, Underscore, imagesLoaded, and Masonry
hook_views_data_alter
Adds custom file_browser_preview field to file_managed table for use in Views
Troubleshooting 5
Ensure all required JavaScript libraries (Backbone, Underscore, imagesLoaded, Masonry) are installed in /libraries directory with correct folder names: /libraries/backbone/backbone-min.js, /libraries/underscore/underscore-min.js, /libraries/imagesloaded/imagesloaded.pkgd.min.js, /libraries/masonry/dist/masonry.pkgd.min.js
The File Browser widget only appears for fields already using it (backwards compatibility). For new fields, use Entity Browser's widget and select 'File Browser' or 'File Browser (Modal)' as the entity browser.
Check browser console for JavaScript errors. Ensure imagesLoaded library is properly installed, as Masonry initialization waits for images to load before calculating grid layout.
Ensure the web server has write permissions to the public:// files directory (typically sites/default/files). The module saves an icon file during installation.
Verify Entity Browser and its dependencies are properly installed. Check that the browse_files_modal entity browser configuration exists and JavaScript libraries are loading without errors.
Security Notes 3
- File access is checked using Drupal's entity access system - users must have 'view' permission on files to see previews
- The upload widget respects configured file extension restrictions (default: jpg, jpeg, gif, png, txt, doc, xls, pdf, ppt, pps, odt, ods, odp)
- Files uploaded through the browser are saved to public:// by default - ensure sensitive files are uploaded to private:// if needed by customizing the entity browser widget configuration