This page contains information on media and the changes D9 has brought to how your assets are managed.

On this page



In Drupal we define Media as any resource, probably with a visual element, and its associated metadata. They consist of a file and hold information like alt text, captions, and metadata.

All Media entities have a single canonical source (file), but the site might display them in different permutations depending on context.

Example: With images, a single JPG file could be displayed as a thumbnail in a grid listing, a large responsive version as the hero image for the home page, or in a figure with a caption in page body.


What this means:

  • Media is reusable.
    • For images, as an example, you can use the same image as the Hero Image, CTA Image, and/or Lead In image. Using the focal point tool will specify which area of the image is focused on in each use case.
  • Media resizes appropriately anywhere it's used.
    • You do not need to resize or rescale images. You only need to ensure the image you are providing is at least as large as the largest size it will appear in.
    • In fact, it is not recommended to size an image to exact dimensions because:
      • It limits the use case of where your image can be reused.
      • Images behave relative to how they're viewed (depending on layout, device, etc) and will never appear in an exact dimension at all time.
    • Best practice: Simply provide an image big enough to cover the use cases you intend to display. 
  • Media is optimized for each use case.
    • Oversized images are of no concern since appropriate size and scale when rendered. The only hard limitation is a 20mb file upload limit which applies to any type of media.
    • Even with a high limitation, providing images and files that are optimized for web to begin with would yield the best results.
  • Media is editable.
    • You can set defaults and override in specific contexts. You can edit any field and it will update anywhere is used so long as it is not overridden.
      • For example: When first uploading an image, you provide an alt-text which will be the default. The alt-text for that image will be set to the default when it is used somewhere. If you want to have a different alt-text for the images shown on a specific page, you can manually configure it for that page. When you edit the alt-text, it will update for instances except for the ones manually overridden.
    • You can change the source.
      • Any reference to media points to the media entity and not the source. You can edit the file and all media using that file will update.
      • For example: with images, updating the source image in a media item will update for all instances where it is displayed.
      • Another example: With documents, you can upload a file called document-1.pdf, and it will be associated with a media path such as .../media/1234/.
      • If you linked to that document using best practices where it is linked to the media path, you will not need to update all of those links if you update the document with a new version. You can edit the media item with an updated version of the file document-2.pdf and all those links will automatically lead to the updated document.
      • This is the reason why it is important to follow correct linking procedures and best practices. The point is to minimize broken links and the need to update existing paths.
      • Best practice:
        • Link to the media path and not the file directly.
        • Update versions of documents by editing existing media and not creating a new one.


Media Types

Media entities get divided up into Media types. It is a similar to the concept of content types or block types where each type defines its own fields and display settings.


  • A locally hosted audio file
  • Allowed types: mp3 wav aac


  • An uploaded file or document, such as a PDF
  • Allowed types: txt rtf doc docx ppt pptx xls xlsx pdf odf odg odp ods odt fodt fods fodp fodg key numbers pages

Hero Image

  • Large scale images to be used as Hero Images on your site
  • Allowed types: png gif jpg jpeg
    • Note: animated gifs will not render 


  • Use local images for reusable media
  • Allowed types: png gif jpg jpeg
    • Note: animated gifs will not render 
  • Tip: Set a Focal Point! This will allow media to centre on a specific focal point when it is cropped.

Remote Video

  • A remotely hosted video from YouTube or Vimeo.
  • You can link to media from the following services: YouTube, Vimeo
  • Warning: Only remote video from the mentioned services are allowed. Locally hosted video is not supported. You will not be able to upload videos.


  • A twitter tweet
  • Link from: Twitter


Media Library

Media Library is a media management tool that enables you to find media that exists within your Drupal site and to add new media items.

Viewing the Library

To view the Media Library, go to:

  • Manage > Content
  • Click on Media tab

Filtering & Operations

Use the filters to find media easier

  • Title refers to the title of the content
  • Type can filter the search by type

The operations column has quick access to the edit and delete button for each media.

  • Edit takes you to the media edit screen where you can make your revisions
  • Delete deletes the content




Adding Media

  1. Go to Manage > Content > Media
  2. Click Add Media
  3. Choose the Type of media you are adding
  4. Provide the source
    • Upload a file (Images, Audio, Documents) or provide the URL (YouTube, Vimeo, Twitter)
  5. Save


Editing Media

  1. Go to Manage > Content > Media
  2. Find the Media you want to edit 
    • Tip: Use the filter to refine the list and make your search easier by setting the media type and/or adding a keyword from the title
  3. Once you find the block you wish to edit, click Edit 
    • You will be taken to the media edit screen where you can make your desired changes.
    • Changes made to the media entity be reflected in all instances where the media is user but retain any overrides.
      • Example: You can edit an image's default alt-text and it will update in all the instances where default is used. If an image was added to the page and it a custom alt-text was set, it will keep custom alt-text.
    • Tip: You can edit even the source! This is the recommended way of updating images or files. Instead of uploading a new version and relinking to it, you can simply update the media item and it will update to use the new source where ever the media is referenced.
  4. Save


Deleting Media

Please note that deleting content is permanent and irreversible.

  1. Go to Manage > Content > Media
  2. Find the Media you want to delete 
    • Tip: Use the filter to refine the list and make your search easier by setting the media type and/or adding a keyword from the title
  3. Once you find the block you wish to edit, click the arrow down button next to edit and click Delete
  4. You will be taken to a confirmation page. Click Delete to confirm.
    • Warning: As with all deletions in Drupal, deleting pages is permanent and cannot be undone.
  5. Save

Deleting a media does not automatically remove it from the place where it was referenced. The media will not be visible to public view. Editors will see a warning for a missing media when they edit the page that reference it and should remove it to clean up.


Media in the Rich Text Editor

The media library is also available within the Rich Text Editor (RTE) by using the Media tool.

Inserting Media

Media can be inserted or embedded in the page in the RTE.

To add a media on any page or field using the RTE:

  1. Edit the page you wish to use insert media in
  2. Place your cursor to the spot where you want your media to appear
  3. Click the Media tool
  4. This will bring up the Media Library dialog.
    • Select the media you would like to insert. Media items you've created through the library before will be listed here and available to be selected.
    • Alternative: You can add new media through this interface by selecting the type and providing a source (either uploading a file or providing a url depending on the type chosen). The new item will appear on the list to be selected.
  5. Click Insert Selected


Configuring Placed Media

Media placed on a page has configurable options available. The availability of each setting will depend on the type of media being placed.

  • Alt-text
    • Alt-text is required for all images. The alt text provided when initially uploading an image is set as the default alt-text.
    • The default can be overridden with a more contextual description by providing an alt-text when placing/configuring media on a page.
    • The override will only apply to that instance
    • Tip: See Accessible Images and Multimedia for good examples of alt-text
  • Alignment
    • None
    • Left: Aligns the block left. ext and adjacent content will wrap around the image.
    • Center: Centres the block within the page / or its container
    • Right: Aligns the block right. Text and adjacent content will wrap around the image.
    • Warning: The editor does not reflect the text wrapping around items aligned left or right
  • Caption
    • Enables the media to be wrapped in a figure. When checked, the media will appear with a yellow border and space under the image for a text caption.
  • View Modes
    • Default
      • Uses the default view when embedded
      • Audio appears as an html audio player
      • Remote video appears as the services' video player
      • Tweets appear as tweets.
      • Documents appear as a link to the media with its file name as the title.


View modes for images only

  • Default
    • It will scale according to its actual width while retaining aspect ratio
  • Banner
    • It will fill the page or its container (max render 1320px) while enforcing a max-height of 500px
  • Landscape
    • This will crop the image to 4:3 ratio (max render 825×550px)
  • Portrait
    • This will crop the image to 3:4 ratio (max render 550×825px)
  • Square
    • This will crop the image to a 1:1 ratio (max render 550px)

"Max render" means this is the largest this view mode will display an image.

To ensure you cover most scenarios, provide an image bigger than the max render.

Example: If you are targeting squares, provide an image that is at least 550px in width.

To configure a media:

  1. Edit the page that contains the media you wish to configure
  2. On the media you wish to configure, click Edit Media
    • This refers to editing how the media displays on the page and NOT editing the contents of media. To edit the content of media such as changing the source, default alt-text and other information, see Media > Editing Media above.
  3. A dialog will appear with configurable options available for the type of media being configured
    • Adjust the desired settings
  4. Save