Including Default Image Styles with Your Theme

Drupal has a powerful image management system that allows the creation of image styles, which can apply various effects to an image and generate derivatives from the original image. This functionality can be used in themes that want to include a default set of image styles designed to work with the theme, rather than relying on those provided by core.

The process of including an image style in your theme is similar to the process of including default configuration in a module.

• Create the image style you want to include using the user interface
• Export the image style as YAML
• Include the exported YAML in your theme’s config/install directory, following the appropriate naming conventions.

Start by creating an image style using the admin interface at Configuration > Media > Image styles (admin/config/media/image-styles). Once the image style is created and saved, the configuration that defines this image style will be stored in your site’s active configuration.

This configuration can be exported using:

• the single import/export tool at Configuration > Configuration Management > Single Import/Export > Export (admin/config/development/configuration/single/export)
• From the configuration type dropdown, select “Image Style”
• Then select your image style from the configuration name dropdown

The YAML representation of the image style will be displayed in a text area and can be copied and pasted into a .yml file in your theme’s config/install directory. Configuration files follow a specific naming convention: image.style.{image style name}.yml. If you’re unsure what your file name should be, it will be shown below the exported configuration text area.

Note that the exported configuration will contain a UUID key as the first line. This UUID should be removed before copying the configuration into the new file image.style.{image style name}.yml.

Example THEMENAME/config/install/image.style.black_white.yml

langcode: en
status: true
dependencies: { }
name: black_white
label: 'black & white'
effects:
  8d4f85cc-9a2d-4a30-af15-21b0833dc06d:
    uuid: 8d4f85cc-9a2d-4a30-af15-21b0833dc06d
    id: image_desaturate
    weight: 1
    data: { }
    third_party_settings: { }

You can include any number of image styles with your theme. All of them will be imported into the active configuration when the theme is installed.

Note that after the theme is installed, editing the image style YML file in config/install will have no effect, nor will adding additional image style YML files to config/install.