Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 37 ยท Content Types and Fields

Media, Images and Image Styles

Manage files in Drupal: image and file fields, alt text, image styles for responsive sizes, the Media module and Media Library, and reusable media entities.

Sooner or later every site needs pictures, PDFs and videos. Drupal offers two ways to handle them. The older way is to attach files directly to content with image and file fields. The modern way is the Media system, where each file becomes a reusable media entity that editors browse in a library. This lesson explains both, and how image styles deliver the right size to every visitor.

File and image fields

The simplest approach is a field on a content type. Add a field of type Image (or File), and configure:

  • Allowed file extensions (jpg, png, webp for images).
  • File directory, which may use tokens like [date:custom:Y-m] so uploads are organized by month.
  • Maximum upload size and optional maximum and minimum dimensions.
  • Alt text and title fields: enable and, for images, make alt text required for accessibility.
  • Cardinality, for galleries.

Uploaded files are stored in web/sites/default/files (the public file system) or in a private location for restricted downloads. Each upload is also recorded as a file entity in the database, with a status (temporary until the content is saved, then permanent) and a usage count that shows where it is used.

Image styles

Original photos are far too big for a thumbnail. An image style is a named recipe of effects applied to an original to produce a derivative file, for example "Thumbnail": scale to 100 pixels wide. Manage them under Configuration > Media > Image styles.

Common effects: Scale (keep proportions), Crop, Scale and crop (fill an exact box), Resize, Convert (to WebP, for example), Rotate. Drupal generates the derivative the first time it is requested and keeps it in files/styles/<style>/public/.... A security token on the URL prevents someone from flooding your server by asking for arbitrary sizes.

On Manage display you select the Image formatter and an image style, and choose whether to link the image to the original file or the content. Different view modes can use different styles: a large hero in Full content, a small square in Teaser.

Responsive images

A single size is a compromise. The Responsive Image module defines responsive image styles that map breakpoints to image styles and produce srcset and sizes attributes, so a phone downloads a smaller file than a desktop. Output looks like standard HTML:

HTML
<img src="/sites/default/files/styles/large/public/cover.jpg"
     srcset="/sites/default/files/styles/small/public/cover.jpg 480w,
             /sites/default/files/styles/large/public/cover.jpg 1200w"
     sizes="(max-width: 600px) 480px, 1200px"
     width="1200" height="800" alt="Students at the open day" loading="lazy">

Drupal adds loading="lazy" for images and width and height to avoid layout shifts.

The Media system

Core's Media and Media Library modules turn files into first-class content. Instead of uploading again and again, editors pick from a library. Core provides media types: Image, Document, Audio, Video (local files), and Remote video (for supported video sites).

Benefits over plain file fields:

  • Reuse one image in many places; replace it once to update all.
  • Fields on media: caption, credit, alt text, copyright.
  • Search, filter and reuse in the Media Library widget.
  • Permissions specific to media.
  • Embedding in rich text with CKEditor (<drupal-media> elements).

To use it, enable the Media and Media Library modules, then add an Entity reference field targeting Media, with the Media library widget. You are using exactly the reference mechanism from Taxonomy and Entity References.

Accessibility and performance habits

  • Always provide alt text. Make it required on image fields and train editors to describe purpose, not just appearance. Decorative images get empty alt.
  • Compress and convert to WebP or AVIF through image styles.
  • Set explicit dimensions to prevent layout shift.
  • Use lazy loading for below-the-fold images.
  • Avoid giant originals: set a maximum upload resolution.

Computing image style output

Real Drupal does the image processing with PHP's GD or Imagick. The stand-in below models only the dimension math of the common effects, so you can reason about what a style does to a given original. It does not process pixels.

JS Stand-in: dimension math of image style effects

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Note that scale never upscales: a 900-pixel original asked for 1600 stays 900.

A reuse counter

Drupal tracks where each file or media item is used, to warn you before deletion. This stand-in demonstrates usage counting, the idea behind the "Used in" column.

JS Stand-in: file usage tracking

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Choosing between file fields and Media

  • A small site with a cover image per article can use a plain image field.
  • A site where images repeat across pages, need credits, or are managed by a team should use Media.
  • Choose early: migrating from image fields to Media later is possible but takes work.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is an image style?

    Styles such as Thumbnail scale or crop the original to make a smaller version.
  2. 2. What is the main advantage of the Media system over a plain image field?

    Media entities are reusable content, with their own fields and a browsable library.
  3. 3. Which attribute helps a phone download a smaller image?

    Responsive image styles output srcset and sizes so the browser can choose a suitable file.
  4. 4. Why make alt text required?

    Alt text lets screen reader users understand images, and helps when images fail to load.

Summary

  • Image and file fields attach uploads directly; the Media system makes them reusable entities in a library.
  • Image styles create derivative sizes; responsive image styles add srcset for different screens.
  • Require alt text, constrain upload sizes and use lazy loading and modern formats.
  • Use Media when images are shared, credited or managed by a team.

Next: Views Basics