Skip to main content

Using the new Media Library in Drupal 8.6

Drupal 8.6 has shipped with the Media Library! It’s just one part of the latest round of improvements from the Media Initiative, but what a great improvement! Being brand new it’s still in the “experimental” module state but we’ve set it up on this website to test it out and are feeling pretty comfortable with its stability.

by rikki.bochow /

That said, I highly encourage you test it thoroughly on your own site before enabling any experimental module on a production site. Don’t just take my word for it :)

What it adds

The Media Library has two main parts to it...

Grid Listing

There’s the Grid Listing at /admin/content/media, which takes precedence over the usual table of media items (which is still available under the “Table” tab). The grid renders a new Media Library view mode showing the thumbnail and compact title, as well as the bulk edit checkbox.

The new media library grid listing page

Field Widget

Then there’s the field widget! The field widget can be set on the “Manage Form Display” page of any entity with a Media Reference Field. Once enabled, an editor can either browse existing media (by accessing the Grid Listing in a modal) or create a new media item (utilising the new Media Library form mode - which is easy to customise).

Media reference field with the new Media Library form widget
Media Library widget once media has been added, which shows a thumbnail of the media

The widget is very similar to what the ‘Inline Entity Form’ module gave you, especially when paired with the Entity Browsers IEF submodule. But the final result is a much nicer display and in general feels like a nicer UX. Plus it’s in core so you don’t need to add extra modules!

The widget also supports bulk upload which is fantastic. It respects the Media Reference Fields cardinality, so limit it to one - and only file can be uploaded or selected from the browser. Allow more than one and upload or select up to that exact number.  The field even tells you how many you can add and how many you have left. And yes, the field supports drag and drop :)

What is doesn’t add

WYSIWYG embedding

WYSIWYG embed support is now being worked on for a future release of Drupal 8 core, you can follow this Meta issue to keep track of the progress. It sounds like some version of Entity Embed (possibly limited to Media) will make it’s way in and some form of CKEditor plugin or button will be available to achieve something similar to what the Media Entity Browser, Entity Browser, Entity Embed and Embed module set provides currently.

Until then though, we’ve been working on integrating the Media Libraries Grid Listing into a submodule of Media Entity Browser to provide editors with the UX improvements that came with Media Library but keeping the same WYSIWYG embed process (and the contrib modules behind it) they’re currently used to (assuming they’re already using Media Entity Browser, of course). More on this submodule below.

This is essentially a temporary solution until the Media Initiative team and those who help out on their issue queue (all the way from UX through to dev) have the time and mental space to get it into core. It should hopefully have all same the bulk upload features the field widget has, it might even be able to support bulk embedding too!

View mode or image style selectors for editors

Site builders can set the view mode of the rendered media entity from the manage display page, which in turn allows you to set an image style for that view mode, but editors can’t change this per image (without needing multiple different Media reference fields).

There is work on supporting this idea for images uploaded via CKEditor directly, which has nothing to do with Media, but I think it would be a nice feature for Media embedding via WYSIWYG as well. Potentially also for Media Reference Fields. But by no means a deal breaker.

Advanced cropping

From what I can gather there are no plans to add any more advanced cropping capabilities into core. This is probably a good thing since cropping requirements can differ greatly and we don’t want core to get too big. So contrib will still be your goto for this. Image Widget Crop is my favourite for this, but there’s also the simpler Focal Point.

Testing out the Media Entity Browser submodule

You can test out the submodule from the patch on this issue and let us know what you think! Once the patch is added, enable the submodule then edit your existing Entity Browsers and swap the View widget over to the “Media Entity Browser (Media Library)” view.

Form for changing the Entity Browser view widget

It shouldn’t matter if you’ve customised your entity browser. If you’ve added something like Dropzone for drag-and-drop support it *should* still work (if not, check the Dropzone or Entity Browser issue queues). If you’ve customised the view it uses however, you might need to redo those customisations on the new view.

I also like updating the Form Mode of the Entity Browsers IEF widget to use the new Media Library form display, which I always pair back to just the essential fields (who really needs to manually set the author and created time of uploaded media?).

You still can’t embed more than one media item at a time. But at least now you also can’t select more than one item when browsing so that’s definitely an improvement.

Modal of the Media Entity Browser showing the same Grid listing

Plus editors will experience a fairly consistent UX between browsing and uploading media on fields as they do via the WYSIWYG.

Once setup and tested (ensuring you’ve updated any Media Reference Fields to use the new Media Library widget too) you can safely disable the base Media Entity Browser module and delete any unused configuration - it should just be the old “Media Entity Browser” view.

Please post any feedback on the issue itself so we can make sure it’s at its best before rolling another release of the module.

Happy days!

I hope you have as much fun setting up the Media Library as I did. If you want to contribute to the Media Initiative I’m sure they’ll be more than happy for the help! They’ve done a fantastic job so far but there’s still plenty left to do.

Posted by rikki.bochow
Front end Developer



Comment by IlchoVuchkov


Nice and useful article of Media Library in core usage into each Drupal 8 project.
Thank you!

Comment by Morgan Cartwright


I'm running the latest Media and Media library in Drupal 8.6.7. I have added a couple additional fields to the Media Image type. So now I can add an image, plus give it a category, a caption, a credit, and a text area. Trouble is, I'm not able to change the image itself once it's been created. With content types, such as article, you can change about everything but the machine name. Am I missing the point? Is this a feature, not a bug?

Comment by rikki.bochow


Hey Morgan, you certainly should be able to, though it's a bit less obvious with the new Grid display... If you click on any existing Media entities title you'll get the Edit tab just like normal content. It might be easier to switch to the old Table display (/admin/content/media-table) and use the edit buttons there.

But once you're on the edit screen of your existing media you can use the 'Remove' button of the image field to remove the current image and upload a new one.

Comment by Nate


Thanks for the summary!

Comment by Joz


It's really an excellent module, do you think it's possible today to use it in production? Thank you in advance.

Comment by Nixsur


Drupal 8.7.0 is available now, there are improvements in Media Library!

Comment by Jidai Kaioku


I'm running Drupal 8.6.15 and when the media library is enabled and I navigate to Media tab I cannot find the Table and Grid secondary tab, although I am using the Seven theme as administrator theme. Also, the tabs do appear in the Contents tab as Overview and Moderated Content.
Am I missing some other settings that need to be done to display the grid/table view tab ?

Comment by Gregor Ruthven


Do you know if there is an easy way to integrate DAMs like Cloudinary into Media Library?