Drupal Media & Image Styles — Managing Images and Media Libraries

In this tutorial, you'll learn Drupal media management including image styles, media entities, responsive images, image effects, the media library interface, and best practices for handling images and document uploads.

What You'll Learn

• File system configuration for public and private file storage
• Image styles and image effects for transforming images
• Responsive image styles for mobile-friendly images
• Media entity types: Image, Video, Document, Audio
• Media library UI for inserting media into content
• Image and file field configuration for content types
• Alt text and title text best practices

Why It Matters

Images and media files account for the majority of a typical website's bandwidth. Properly configured image styles, responsive images, and media management ensure fast page loads, good SEO scores, and a professional visual presentation. The Media module in Drupal core transforms media handling from simple file uploads into a structured content system.

Real-World Use

A photography portfolio site uses Drupal media with image styles configured automatically. When a photographer uploads a 4000x3000 pixel RAW export, Drupal generates eight derived image derivatives: thumbnail (100x100), small (300x200), medium (600x400), large (1024x683), hero (1920x1080), gallery thumbnail (200x200 crop), and card (400x300 crop). Responsive images serve the appropriate size based on the Visitor's viewport. The media library stores all images with keywords and categories.

Learning Path

flowchart LR
  A[Views] --> B[Media & Image Styles]
  B --> C[Revisions]
  C --> D[Blocks]
  D --> E[Menus]
  E --> F[Layout Builder]

File System Settings

Configure file storage at Configuration > Media > File system (or /admin/config/media/file-system).

Public File System

Files stored in the public directory are accessible directly via URL. Use for images, CSS, JS, and other public assets.

Path: sites/default/files
URL: https://example.com/sites/default/files/images/photo.jpg

Private File System

Files stored in the private directory are served through Drupal's access control system.

Path: sites/default/private
URL: https://example.com/system/files/images/photo.jpg
Access: Must have permission to view private files

Configuration

<?php

// settings.php configuration
$settings['file_public_path'] = 'sites/default/files';
$settings['file_private_path'] = 'sites/default/private';
$settings['file_temp_path'] = '/tmp';

Image Styles

Image styles define a series of image effects applied to uploaded images. The original file is preserved, and derived images are generated on demand.

Navigate to Configuration > Media > Image styles (or /admin/config/media/image-styles).

Default Image Styles

Drupal provides several default image styles:

• Thumbnail: 100x100
• Small: 220x220
• Medium: 220x220 (different crop)
• Large: 480x480
• Wide: 1090x613

Creating a Custom Image Style

# Custom image style configuration
Name: Hero
Machine name: hero
Effects:
  - Scale and crop:
      width: 1920
      height: 600
      anchor: center-center
  - Convert:
      extension: webp

Image Effects

Drupal core provides these image effects:

Image Effect Configuration

# Scale effect
effect:
  id: image_scale
  data:
    width: 800
    height: 600
    upscale: true

# Scale and crop effect
effect:
  id: image_scale_and_crop
  data:
    width: 400
    height: 300
    anchor: center-center

# WebP conversion
effect:
  id: image_convert
  data:
    extension: webp

Responsive Image Styles

Responsive image styles serve different image sizes based on the viewing device.

Navigate to Configuration > Media > Responsive image styles (or /admin/config/media/responsive-image-style).

Configuration

# Responsive image style for article content images
Name: Article Image
Breakpoint group: olivero
Fallback image style: medium

# Breakpoints and styles:
# - Default (mobile): small
# - Mobile (480px+): medium
# - Tablet (768px+): large
# - Desktop (1024px+): hero

Breakpoint Groups

Breakpoint groups define screen width thresholds. Olivero (the default theme) provides these breakpoints:

• Mobile: 0 - 479px
• Mobile (narrow): 480px - 767px
• Tablet: 768px - 1023px
• Desktop: 1024px+

Media Entity Type

The Media module provides reusable media entities. Navigate to Structure > Media types.

Default Media Types

• Image: Image files with alt text and title
• Video: Video files (remote or local)
• Document: PDF, DOC, XLS files
• Audio: Audio files

Creating a Custom Media Type

# Media type: Gallery Image
Name: Gallery Image
Machine name: gallery_image
Source: Image
Field mappings:
  name: Image Title
  field_media_image: Image (from source)

Media Fields

Media types can have custom fields:

• Image: field_media_image (source field)
• Description: field_media_description (text formatted)
• Credit/Attribution: field_media_credit (text)
• Copyright: field_media_copyright (text)
• Categories: field_media_categories (taxonomy)

Media Library UI

The media library provides an insert interface for content editors.

Opening the Media Library

When editing content with a media field, click "Add media" to open the media library.

Media Library Features

• Grid view: Thumbnails of all media items
• Table view: List view with metadata
• Search: Search by media name
• Filters: Filter by media type and taxonomy
• Upload: Upload new media directly
• Select: Choose one or multiple items for insertion

Media Library Configuration

# Media library settings
Media library:
  Grid columns: 4
  Default view: grid
  Allow upload: true
  Enforce minimum dimensions: true
  Minimum width: 500
  Minimum height: 500

Media Field on Content Types

Add a Media field to content types for rich media integration.

Field Configuration

# Media field on Article content type
Label: Featured Image
Machine name: field_featured_image
Field type: Entity reference
Referenced entity type: Media
Media type bundle: Image
Widget: Media library
Allowed number of values: 1

Formatter Configuration

# Media field formatter
Formatter: Responsive image
Responsive image style: hero
Image link: content

Image Field Formatters

# Image formatter configuration
formatter:
  type: image
  settings:
    image_style: large
    image_link: file

File Fields and Uploads

File fields allow uploading documents and other non-image files.

# File field configuration
Label: Brochure PDF
Field type: File
Allowed extensions: pdf doc docx
File directory: brochures
Upload size: 10 MB

File Display Formatters

# File formatter: link
formatter:
  type: file_link
  settings:
    label: 'Download PDF'

# File formatter: table
formatter:
  type: file_table
  settings:
    displayed: true
    description: false

Alt Text and Title Best Practices

Accessible images require proper alt text and titles.

Alt Text Rules

• Describe the image content for screen reader users
• Keep under 125 characters
• Do not start with "image of" or "picture of"
• For decorative images, use empty alt text
• Include keywords naturally when relevant

Title Text Rules

• Provides additional context on hover
• Optional, not required for Accessibility
• Can include more detail than alt text
• Used as tooltip in some browsers

Programmatic Access

<?php

// Get alt text from image field
$node = \Drupal::entityTypeManager()
  ->getStorage('node')
  ->load(42);
$image_field = $node->get('field_image');

if (!$image_field->isEmpty()) {
  $item = $image_field->first();
  $alt = $item->get('alt')->getValue();
  $title = $item->get('title')->getValue();
  $uri = $item->get('entity')->getFileUri();
}

Common Mistakes

1. Not creating enough image styles: Using the full uploaded image for every display context wastes bandwidth. Create dedicated image styles for thumbnails, cards, hero sections, and full-page views.
2. Ignoring responsive images: Serving 1920px hero images to mobile users wastes data and slows page load. Always configure responsive image styles with breakpoints.
3. Not setting alt text on images: Missing alt text fails WCAG accessibility Compliance and hurts SEO. Enforce alt text requirements on image fields.
4. Using public file storage for confidential documents: Any file in the public directory is accessible without authentication. Use private file storage for member-only documents, invoices, or sensitive downloads.
5. Allowing unlimited file size uploads: Large uploads consume server disk space and cause timeouts. Set appropriate upload size limits per field.

Practice Questions

1. What is the difference between public and private file storage in Drupal, and when would you use each?
2. How do image styles work in Drupal? Explain the difference between Scale and "Scale and crop" effects with examples.
3. How would you create a responsive image setup that serves a 300px-wide image on mobile, 600px on tablet, and 1200px on desktop?
4. Challenge: Set up a complete media management system for a news website. Create image styles for thumbnail (100x100 crop), card (400x300 crop), article-full (800x600), and hero (1920x600 crop). Create responsive image styles for article images and hero banners. Create a "Photo" media type with fields for Image, Caption, Credit, and Category. Add a media reference field to the Article content type. Configure formatters to use responsive image styles. Write a Drush command that regenerates all image derivatives for a given content type.

FAQ

Mini Project

Goal: Build a complete media management system for a photography portfolio.

1. Configure file system: Set public path and ensure proper permissions
2. Create image styles:
   • thumbnail (100x100, scale and crop)
   • gallery-card (400x300, scale and crop)
   • gallery-large (1200x800, scale)
   • hero-banner (1920x600, scale and crop)
3. Create a responsive image style for gallery images (mobile: gallery-card, tablet: gallery-large, desktop: original)
4. Create a "Photograph" media type with fields: Image, Title, Description, Camera Settings (text), Location (text), Date Taken (date)
5. Add a "Photo Gallery" content type with: Title, Description, Photos (entity reference to Photograph media, unlimited), Cover Photo (single entity reference)
6. Configure the media library for easy image selection
7. Create Views for the gallery listing and individual gallery pages
8. Ensure all image derivatives display correctly at each breakpoint

What's Next

With media management configured, learn how to manage content versions with Revisions and Content Moderation. Then explore Blocks and Layout for arranging content in theme regions.