Image style

An image style is a configuration entity of the core Image module that holds an ordered list of effects, such as scale, crop or rotate. Drupal applies the effects to an uploaded image the first time that style is requested and keeps the output as a derivative file, so one upload can appear as a thumbnail, a card image and a full-width banner.

How image styles work in Drupal 11

Each style has a label and a machine name. The core help says the label shows in the admin pages and the machine name is used to build the URL of a processed image. Core ships these effects as plugins: Convert, Convert to AVIF, Crop, Desaturate, Resize, Rotate, Scale and Scale and crop. Contributed modules can add more. Effects run in the order shown on the style, and you can drag them to reorder.

The ImageStyle class builds the derivative path as styles/{style}/{scheme}/{original path} under the file scheme, and adds an extension when an effect changes the file type. On the first request, ImageStyleDownloadController checks the request, creates the file with createDerivative() and sends it. Later requests get the saved file. The URL carries an itok query token; core checks it. The allow_insecure_derivatives setting in image.settings ships as false and can relax that check.

A style is applied where a field formatter shows an image: the Image formatter has an Image style setting, with the option None (original image).

Example

Go to Configuration › Media › Image styles and click Add image style. Name it, then choose an effect such as Scale, enter a width and height, and save. Then open Manage display for a content type with an image field and select the new style in the Image formatter settings. You need the "administer image styles" permission for the first part.

Common mistakes

• Uploading huge originals and showing them unstyled. With None (original image) the browser downloads the uploaded file as is.
• Blaming the style for an old image. Core deletes derivatives when a style is saved and when a file is deleted or moved. If an old picture persists, check a browser, CDN or proxy cache, or whether the original was replaced on the server outside Drupal.
• Enabling insecure derivatives to fix a missing image. The source comments describe the token as denial-of-service protection and say the bypass raises that risk. Fix the link that lacks the token instead.
• Using one style for every size. A fixed 650 pixel scale cannot serve both a phone and a wide hero; that is the job of a responsive image style.

For marketing and content teams

Editors upload one good, large image and the site produces the sizes. If a picture looks cropped or soft, ask which image style the page uses before you replace the file, because the fix may be one effect on the style rather than a new upload. The Image module installs four styles: Thumbnail (100×100), Medium (220×220), Large (480×480) and Wide (1090). The Standard profile adds Max 325x325, Max 650x650, Max 1300x1300 and Max 2600x2600 as optional configuration, which installs only together with the Responsive Image module.

Sources

• Drupal User Guide: Concept: Image styles
• Drupal core 11.4.10: Image module help text
• Drupal core 11.4.10: ImageStyle entity class
• Drupal core 11.4.10: ImageStyleDownloadController
• Drupal core 11.4.10: Help topic Adding an image style
• Drupal core 11.4.10: Image effect plugins
• Drupal core 11.4.10: image.settings.yml
• Drupal core 11.4.10: Responsive Image module help text
• Drupal core 11.4.10: Image module install configuration
• Drupal core 11.4.10: Standard profile optional configuration
• Drush image:flush command