Drupal 8 Basic Media and Media Browser Setup for beginners

Jaime Contreras
Jaime ContrerasSenior Web Developer
Drupal 8 Basic Media and Media Browser Setup for beginners

This is a beginner’s tutorial that will quickly get you up and running with media entities and a media entity browser in Drupal 8.

One of the best parts of Drupal 8 is the in-core feature of media entities. This allows Drupal to manage resources that otherwise it would not be able to. It accomplishes this by creating a bridge relationship between Drupal’s CMS, media files and external sources. It’s basically an entity referencing all kinds of media files like images, videos, documents or other external sources like Tweets, embed videos, etc.

This tutorial is for the core “media” module set up, not to be confused with the contributed module “media_entity” module. If your Drupal setup already has this module and its sub-modules enabled in your setup, you may want to migrate your setup to the core module “media” following the instructions on the project page at https://www.drupal.org/project/media_entity

First Things First, Enable the Media Module:

Enable the media module (NOT entity_media). The “media” module comes with Drupal core so you don’t need to install it. All you have to do is enable it.

Using the Drush command:

drush en media -y

- Or: In the Drupal’s interface, go to /admin/modules, search for media in the search box, check the Media module and install to enable the module.

Configure or Create Media types:

Once the Media module is enabled, it will create the basic media types. You can find these under the structure menu. Media types are entity types just like nodes allowing you to add custom fields and adjust or make new displays to your needs.

To keep things simple in this tutorial, I will concentrate on the “Image” Media type. But you can apply the same principals to any other type. The difference will be on how the sources are being added and display just like node types.

Display the "name" field (optional) :

It's my personal preference to always enable the “Name” field in the forms of media types. This way you will be forced to add a name to your media type that you can later use for searching in the media browser.
(For even more searching options, you can add taxonomy tag field to group resources and so on. But for this example, let’s keep it simple.)

For this example navigate to /admin/structure/media/manage/image/form-display

Now drag into the content area “Name” field and drag to hide or disable all other fields with the exception of the “Image” field, so all you have displayed on the form is the image and name field. This will come in handy when creating the media browser view in the next step.

Installing the Entity Browser Modules and Creating Media Browsers:

The media browser is what you will use to pick and add new images to the content where the media entity reference field is being used. It basically adds a widget for your field. The media entities can also be managed via the content page in the “Media” tab.

Install these Modules: Chaos Tools, Entity Browser:

composer require drupal/ctools
composer require drupal/entity_browser
composer require drupal/inline_entity_form

Then enable Chaos Tools, Entity Browser, and Entity Browser IEF.

drush en ctools, entity_browser, inline_entity_form, entity_browser_entity_form

- Or: In the Drupal’s interface, go to /admin/modules  Ctools, Entity Browser, and Entity Browser IEF (you may have to enable the entity browser first).

Create a View to Use in the Media Browser.

We create this view first, in order to use it in the media browser we will create later, to list the available images in the media browser.

1. Go to /admin/structure/views/add:

  • Name your new view “Image Media Entity Browser Listing” 
  • View Settings: Show: Media of type: Image sorted by: Newest first
  • Click on Save and Edit

2. Now Configure the view:

  • Top left under “Displays” click on the “+Add” button and select “Entity browser
  • FORMAT: pick Table
  • Add FIELDS:
    • Name
    • Thumbnail - options:
      • Label: Thumbnail
      • Formatter: Image
      • Image Style: Thumbnail
    • Entity browser bulk select form - options:
      • Label: Select
  • Rearrange the fields in this order: Entity Select, Thumbnail, Name
    • Name (media) - options:

      • Check the “Expose this filer to visitors
      • Label: Search by name
      • Operator: Contains
  • Save the view.

Create the Entity Browser for Image media:

Got to /admin/config/content/entity_browser and click on the “+Add Entity Browser” button.

  • General Setting tab:

    • Label: Image Media Entity Browser
  • Widget Settings tab:
    • Add widget plugin:

      • View - options:

        • Label: Image Library
        • Submit button text: Select
        • View, view display: Media Browser: Image Media Entity Browser Listing
      • Entity Form - options:
        • Label: Image Upload
        • Submit button text: Upload
        • Entity type: Media
        • Bundle: Image
        • Form mode: Default

Create a Media Entity Reference Field to Use the Image Media Browser

Congrats! So you already set up the media entities and the media browser. Now all you have to do is start using it on your content builds.

  • Go to the content type where you want to add a "New Image" media field

    • Go to Manage Fields:

      • Add a new field of type “Entity Reference: Media”
      • For “Reference Type” pick “Image”
      • Save the new field
  • Now go to the Manage form display:

    • In the new entity reference field change the widget type from Autocomplete to Entity Browser, and set it’s options to:
      • Entity Browser: Image Media Entity Browser
      • Entity Display Plugin: Render Entity
      • View Mode: Default
      • Display Replace Button: Checked
      • Show widget details as open by default: Checked
      • Selection Mode: Append to selection
      • Update field and Save Changes to the form display



Now, whenever you're creating content, you will have a field that opens the media browser on a modal window with options to search, select, and upload new images.


That’s it! - Now all you have to do is repeat the process, configure things to your preferences and soon you will be a pro on media entities. Next, I’ll add a few other recommendations if you want to improve upon your setup.

Recommended modules that can add more power to your entity setups:

Migrating Existing File Fields:

If you are working on an existing Drupal 8 setup and you want to migrate old file fields to a media entity field, follow this tutorial for instructions: Basic Migration Of File Fields To Media Entities.

Happy coding!