Reusable Media in Drupal 8 - it's a reality, here's how!

Drupal 8 reusable media

Reusable Media in Drupal 8 - it's a reality, here's how!

Adding media (for most people that means adding images) in Drupal has been an issue for a long time. Adding reusable media (upload an image once, use it on any page on your website) has been even trickier.

With the advent of Drupal 8 and the sterling work done by the media team, adding reusable media (in a very user friendly manner) is now a reality. This tutorial shows you how:

Step 1 - Download and Install these Modules:

  • Media Entity (the base media module that other media modules can extend from)
  • Media Entity Image (or one of the other media entity type modules - Media Entity Instagram, Media Entity Twitter, Media Entity YouTube, etc)
  • Entity Browser (so you can browse through your existing media library and other entites to reuse them on your page)
  • Inline Entity Form (thanks to Drupal Commerce, this allows you to create new media items and/or select from your existing library)

Step 2 - Create Media Bundles

Navigate to /admin/structure/media and add a media bundle - for example "Image":

Drupal 8 Add media bundle interface

You will be asked to define a field to use as the image field, you can't do that yet as you have not created any fields.

Save the page, and then use the UI to add a new field to your image media bundle - at a minimum you will need an image field.

Drupal 8 media manage fields interface

Click the edit button to edit the image media bundle and check that the image field is now set as the field that the image will be sourced from.

Drupal 8 media file source field interface


You now have a media bundle for images. It's a similar process for creating other media types.

Step 3 - Add a Media Field to a Content Type

Navigate to the "Manage Fields" page of one of your content types and add a new field. Choose field of type "Other" under "Reference" (yes, it could be a little more intuitive!).

Drupal 8 media field type "other"

On the following page, choose the type of entity that this field will reference/use - in our case "Media".

Drupal 8 Media choose entity reference type

On the following page, scroll to the end and select the types of media bundles that can be referenced from this field. In our case, we only have image at the moment. Save the page.

Drupal 8 Media select media bundles to reference - image

You now have a field that allows you to reference uploaded images using the entity reference widget. This means the image needs to have already been added to your site (at /media/add/) and that you know the name you gave to the image when adding it. Your node edit form will have a field like this:

Drupal 8 Media reference image entity on node edit form

Whilst this works, it doesn't allow us to add new images from here. Enter the wonderful Inline Entity Form module.

Step 4 - Create New Media/Use Existing Media - inline

Next, go to the "Manage Form Display" page on your content type. Find the reusable image field and change the widget from 'autocomplete' to 'Inline Entity Form - complex' (don't worry, it's not complex!).

Drupal 8 Media inline entity form

Click the settings cog on the right and set the inline entity form to be able to both add new media and use existing media:

Drupal 8 Media inline entity form settings

Now, when you are on your node edit page you will see an interface like this for your reusable image field:

Drupal 8 Media reusable media interface

"Add new media" will open up the form that is found at /media/add and let you add the media inline here.

Drupal 8 Media inline entity form form

After filling out this form, be sure to click on the "Create media" button. You will then see this:

Drupal 8 Media uploaded image interface

If you had chosen "Add existing media" from a few screenshots above, you will be given the same autocomplete interface that you saw earlier. This is because the Inline Entity Form is not yet using the "Entity Browser" module to search for your media.

Step 5 - Entity Browser Setup

To make this a little easier, I also installed the Entity Browser sub-modules "Entity Browser Test Modules". Then, navigate to /admin/config/content/entity_browser and choose "Add entity browser". In my case, I gave it a name of "Image Browser". I left all the settings as default until I got to the last screen "widgets".

I added a widget of type "Upload" and gave it a human readable name of "Add New Image" and added a widget of type "View" and gave it a human readable name of "Reuse Existing Image" (then chose the "test" files browser view as the view that I would use to find my files).

Drupal 8 entity browser widgets

A caveat - I couldn't get this to work with the Inline Entity Form (it's possible in code - see the "hook_inline_entity_form_reference_form_alter()" in "entity_browser_entity_form.module"). However, there is a UI being built for it which should be ready soon, so I decided to wait for that.

In the meantime, on the content type "Manage Form Display" page, if you set your reusable image field to use "Entity Browser" you can see what it will be like when it's working fully. This (an example of the browser using an iframe:

Drupal 8 entity browser using iframe

And that's about it, a quick roundup of how to add reusable media to your Drupal 8 website - it's almost the holy grail and once we have entity browser working with the inline entity form, it will be the holy grail.

Thanks and well done to all on the media team (of which I have been only a very peripheral part).


or just FTP your files to a directory structure you create in public (usually sites/default/files). Then add the IMCE editor to the default ckeditor and you can browse the public area and insert images into content. I use this in conjunction with the Juicebox module for Drupal 8. Create galleries on the PC, ftp them to a jboxgalleries directory under sites/default/files and access them from any content entry screen using IMCE.

Annertech's default 'Annertechie' profile image.

Hi Frank

Thanks for the comment. We tend not to use inline images on our websites, preferring to have each image part of a dedicated image field. It leads to more expected formatting for the images, less technical debt when rebuilding projects, and easier administration for our content editors.

We also don't use FTP - there are security vulnerabilities with it, and, again, we wouldn't like our clients to have to use an FTP program just to add images into their sites.

Your galleries solution seems like a very easy to use one. I might have a look at that for one of my personal sites.

Thanks again,


Mark Conroy - Lead Frontend Developer & Content Strategist

Thanks for the write-up, that is useful. There's not a great deal of documentation on Drupal 8 media yet.

One thing that I'd really like to see next is better integration between Media and CKeditor in Drupal 8. I take your point about not adding images inline (likewise, I prefer to avoid) - but clients do still expect to be able to do so. At the moment this is one area where Drupal struggles against Wordpress.

Annertech's default 'Annertechie' profile image.

Great to see Media is coming along further. Now if only I could get the inline media entities to work properly with paragraphs (As happens when you add paragraphs to paragraphs etc)

Annertech's default 'Annertechie' profile image.

Another approach to this situation is a custom module I wrote (documented on my blog) that uses Apache Solr for indexing images, since it provides a much better search experience , especially when your image count gets very large. We use the really great S3FS module to store everything in an S3 bucket, and then the module indexes image data into Solr. Using FileField Sources, it creates a custom source that provides a Ctools modal window to search for the image and then insert it back into the image field. It's much lighter, since it's using just a small custom module and FileField Source hooks, along with a Solr index that is already in use elsewhere on the site.

Annertech's default 'Annertechie' profile image.

Hi Mark,

Thanks a lot for this very welcome addition to our D8 toolbox.

I have one question though: how would you output the reused image in a Twig template? I've had no luck so far.

The following is supposed to work but it actually doesn't:

{{ file_create_url ( content.field_reusable_image[0]['#url'].entity.values ) }}

Do you have any input to share here? Shall this be preprocessed in *.theme? Thank you!

Annertech's default 'Annertechie' profile image.

thank you very much for this great tutorial.
I was struggeling for hours because after successfully following your first 3 steps i had no widget 'Inline Entity Form - complex' beside my field i could choose at "Manage display form".

When i referenced "Content" instead of "Media" (as you have shown it in the second screenshot) i could successfully choose 'Inline Entity Form - complex'.

Annertech's default 'Annertechie' profile image.

Hi Torsten, You should be able to use inline entity form for any entities - media, content, taxonomy, etc.
Mark Conroy - Lead Frontend Developer & Content Strategist


Does this module allow to show uploaded video also?


Annertech's default 'Annertechie' profile image.

Hi Hiral, Yes, it works for all media types.
Mark Conroy - Lead Frontend Developer & Content Strategist

Hi Mark,
Is there any progress on the possibility to add media from the library directly within the WYSIWYG editor?
If we are stuck on this particular issue, is there an alternative approach you would recommend?
Thank you for your answer and KUTGW!

Annertech's default 'Annertechie' profile image.

I'm not sure what the progress is with this an the wysiwyg. To be honest, we'd strongly encourage you to not use a wysiwyg, especially for media. Sorry for not much of an answer, but it's one area of media I have very little knowledge of. Instead create a media paragraph type and text paragraph type so users can type text in the text block and add media whenever they want. It means you can more easily style the media items but also make them available for consumption by apps and other things.
Mark Conroy - Lead Frontend Developer & Content Strategist

Maybe a stupid questions, but how do I insert the uploaded images into specific locations in the text? The insert module is not yet ported to Drupal 8...

Annertech's default 'Annertechie' profile image.


See my answer above ^.

"I'm not sure what the progress is with this an the wysiwyg. To be honest, we'd strongly encourage you to not use a wysiwyg, especially for media..."

Mark Conroy - Lead Frontend Developer & Content Strategist

Ah ok, now I see it. I still need to check out the paragraphs module. The problem is just, that it could be really annoying if you have to paste long texts with many pictures, so you have to split it up in many parts. I also han
Btw. I have found the Entity Embed Module which provides the functionality I was searching for.

I tried to assign the Entity Browser to a normal image field instead of using media entity. After uploading images on an article edit site, the whole image form just disappears.

Annertech's default 'Annertechie' profile image.

Ok, after flushing caches it doesn't disappear anymore ;). But unfortunately when using entity browser it ignores the upload path (with tokens) of the image field and put all the images in the files root.

Annertech's default 'Annertechie' profile image.

Hi Mark.

how can i output the the image url, from the field in my content type, in my twig node template? I need only the url.

Best regards

Annertech's default 'Annertechie' profile image.

Hi, after I select an entity in edit mode and save the node, I only get the label and the entity name as link on the page, I don't get the rendered entity. I checked the field settings but don't see where I can change a setting that would make it display. I see I can hide the label or not link the title, but nothing to force the image to display. Any ideas?

Annertech's default 'Annertechie' profile image.

Hi, disregard my last comment, I figured it out. I was looking at and setting the bundle but forgot to check the settings for the content type I added the field to. Once I changed that to rendered entity it worked fine.

Annertech's default 'Annertechie' profile image.

Add new comment

Restricted HTML

  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd> <h4> <h5> <h6>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.