How to Use the New Media Module Features in Drupal

How to Use the New Media Features in Drupal 8.4

Since the release of Drupal 8.4 in late 2017, Drupal has contained new media handling features.

For many years, Drupal has shipped with almost no media handling. This was the most commonly requested feature whenever we did Drupal training.

In this tutorial, we’ll walk you through how to use Drupal’s new media options. We’ll update this post as soon as Drupal 8.5 is available.

Step #1. Install a Contrib Module

The core of Drupal 8.4’s media features is a new “Media” module. This module is available, but hidden by default.

To active the Media module you need to install and activate a contrib module for the media type you want to use. At the moment, there are ten modules that are ready:

  1. Document
  2. Image
  3. Audio
  4. Slideshow
  5. Video embed field
  6. Twitter
  7. Instagram
  8. SlideShare
  9. Facebook
  10. Inline entity form

If you want a complete, updated list of Media modules that are ready for 8.4, bookmark this page.

After installing and enabling a contrib module, Drupal will ask you to enable the Media module too. The Media module is hidden by default and will only become available when enabling contrib modules.

Step #2. Create the Media type

Now, we’re going to create the entity that will store our tweets.

  • Go to Structure > Media types.
  • Click “Add media type”.

twitter media type

One of the more advanced features of the Media module is field mapping. If you want to, you can extract multiple types of data from the tweet and store them in different fields.

field mapping

  • Finish saving your new media type.
  • Click “Manage display” for “Twitter”.

manage display

  • Change the display of “Tweet Url” to “Twitter embed”.

twitter embed manage display

Step #3. Create the Fields

Next, we’re going to add our new media type to a content type.

  • Go to Structure > Content types.
  • Create a new field for a content type, choosing the “Media” field type:

add drupal media field

  • Click through and choose “Twitter” in the “Bundles” area.
  • Don’t check “Create referenced entities if they don’t already exist” because that led to errors in my testing.

media bundles

  • After saving your field, click “Manage display”.
  • Change the display for your new field to “Rendered entity”:

manage display twitter

Step #4. Add the Media

At this stage of Drupal 8’s media journey, we will need to create the media items before we use them.

  • Go to Content > Media.
  • Click “Add media”.
  • Choose “Twitter”.


  • Save the tweet and the next image shows what you will see.
  • If you don’t like the display, go back to Structure > Media types > Manage display and tweak the options.

drupal84 tweet

#5. Use the Media

Finally, let use our new created media inside a node:

  • Go to Content > Add content.
  • Create new content.
  • You’ll be able to search for your existing tweet using an autocomplete field:

tweet publishing drupal

  • Save your content type, and there’s the embedded tweet:

tweet embedded drupal

If you want to learn more Drupal, join OSTraining now. You’ll get access to a vast library of Drupal training videos, plus the best-selling”Drupal 8 Explained” book!


  • Steve Burge

    Steve is the founder of OSTraining. Originally from the UK, he now lives in Sarasota in the USA. Steve's work straddles the line between teaching and web development.

0 0 votes
Blog Rating
Notify of
Newest Most Voted
Inline Feedbacks
View all comments

Does this change alter the way the Migrate module imports media? My D6 to D8 imports pull all images as unintelligible strings of characters rather than as images.

Marcos Cano (marcoscano)

Thanks for writing this post!

Just a small clarification regarding the caveats you mention at the end:

The reason why the Media module is hidden in 8.4 is that users are discouraged to create new sites using it, unless they are willing to build the “missing pieces” themselves (or contribute to getting them done). There is a whole set of features ( considered “necessary” for the Media handling in Drupal to be at an MVP level. Nobody really knows when they will all be complete, but the current goal is to try to have them ready by Drupal 8.5.x.

Before that, users can safely continue building sites with Media Entity 1.x, once there will be an upgrade path for existing sites that want to use Media in core in the future. More information can be found on the Media Entity module page (, and on the Media documentation guide (



Hi, really confused about how to use media now. Starting a new Drupal 8.4 project. Should I use media entity 8.x-1.x + other media contrib 1.x modules and wait until upgrade path is ready? Or should I enable core media and use contrib media modules with their latest 2.x branches e.g. Entity Browser 8.x-2.0-alpha2, so no upgrade then necessary ?

Tom Thorp

Any modules that are 8.x-2.x specific are designed with Core Media in mind. At the moment not all media modules have been rewritten for Core Media, so this may influence your decision. When Core media and it’s modules becomes stable, there will be an upgrade path to migrate all media entity modules to its Core Media equivalents.


Marcos Cano, thank you for sharing this valuable info.

Nic Rodgers

You can use the module with to enable you to add media during the process of creating a node. These modules in combination with Media provide a really powerful and easy-to-use experience for authors to work with media and nodes. We’ve been using it for a couple of months now and our content team love it.


OOOOOH thank you very much !!! Awesome !!!


I’m happy that there is good progress on this, but caveats #1 and #2 are pretty much the main use case from a content editor perspective so I’m not sure it’s actually usable in the real world at this stage…

Ampatzis Yannis (Rockabelly)

Thank you very much for the post, it is very very instructive. If you don’t mind mind I would like to add that there are two very useful modules that could be added to your list, Entity Browser (entity_browser) and DropzoneJS (dropzonejs). Thanks for the post.

Ampatzis Yannis (Rockabelly)

I’m sorry but I forgot to mention that this might be a solution to Caveat #1 and Caveat #2.

James Harrison

There are patches and information to be found at
Look for media issues to stabilize in 8.5 If you installed with composer or have drupal CLI then bin\drupal module:install media for Commerce 2.x or vendor\bin\drupal module:install media for standard from HEAD will enable core media types Image & File at admin/structure/media and allow adding media types. This may help those looking to do reusable image media.

Thomas Moseler

As this is the only Documentation currently to be found on using the new core media module:
There is one important error.
When adding a new field to your content type/entity, there is no media type field to be selected.
What you need to add is an Entiy Reference Field that references content.
In the next step, when you select the content bundle, it is possible to select a Media type you have created.


Regarding your Caveat #1, the Inline Entity Form module works well with Media Entity module and will allow you to create Media while creating content.

Regarding your Caveat #2, You can create a very good “browsable media library” using the Media Entity Browser module.

I’ve been using the Media Entity module with Media Entity Image, Inline Entity Form, Media Entity Browser modules on a couple of production sites. The contrib modules mentioned above helps to create a very intuitive and productive workflow when creating content that contains media in D8.

Tom Thorp

I haven’t found much documentation on the internet to do with field mapping in the core media module. I have been able to create additional metadata fields to the media type and linking it in the ‘field mapping’ section. However I haven’t found a way where information from the media type (such as caption, thumbnail, image size, etc.) can be captured and referenced via tokens. Is this a feature ‘to be developed’ in a future release, or am I missing something?


A long way to go. we should not be required to “Create” the Media entiries in first place to be able to use them.

Others (WordPress) are allowing direct embeds. I understand Media in Drupal can serve more use-cases but the elementary use-case should be fulfilled out of box.

J Mc

I am on 8.5 now and am struggling with media. According to this article it says that in order to activate the new media module in core you “you need to install and activate a contrib module” but I can’t do that. I tried installing the Twitter contrib module but cannot activate it as it says that I have to install Media Entity in order to use the Twitter mod. So now if I install Entity that overrides the media in core and it’s full circle again. I guess I can install Entity and then go through the upgrade path.


I ran into the same problem and realized I was one version short of the one required to use media in core. Make sure you have the 8.x-2.0 version of media_entity_twitter. I still have lots of frustrations but I just cleared that one off today.

Would love your thoughts, please comment.x