controls the style of every image at a website is there a way to overwrite the image.html.twig for a given field let's call it


The field template would be


what would the templates name for the image.html.twig be that just overwrites the output of the img tag for the image in the field?

2 Answers 2


One quick way of achieving this is to preprocess the field before it reaches Twig (in MYTHEME.theme) like this:

 * Implements hook_preprocess_HOOK().
function MYTHEME_preprocess_field(&$variables, $hook) {
  if ($variables['field_name'] == 'field_avatar') {
    if (!empty($variables['items'])) {
      foreach ($variables['items'] as $delta => &$item) {
        $item['content']['#item_attributes']['class'][] = 'foo';

Core's template_preprocess_image_formatter() then takes care of putting #item_attributes and the class into the <img> tag for you.

The normal way of offering alternative template names based on context is implementing hook_theme_suggestions_HOOK() or hook_theme_suggestions_HOOK_alter(). In this case the latter as MYMODULE_theme_suggestions_image_alter().

But the problem here is that there's not much context about the field which will eventually wrap this image at this point. template_preprocess_image_formatter() only carries through the attributes that will end up on the image element itself.

You could be a bit sneaky and use the fact that we have already put the class (or some other identifier) into #item_attributes when preprocessing the field and use that to generate a new template name for the image once it gets to be rendered:

 * Implements hook_theme_suggestions_HOOK_alter().
function MYTHEME_theme_suggestions_image_alter(&$suggestions, $variables) {
  if (!empty($variables['attributes']['class'] && in_array('foo', $variables['attributes']['class'])) {
    $suggestions[] = 'image-foo';

It has the side-effect of adding an extra class (or other attribute) in your tag by default, but since you could now create image-foo.html.twig you could probably compensate for that in the template by removing it there if absolutely needed.

Now just make sure your "field identifier" is fairly unique (and recognizable) so you can figure out where that template suggestion in your theme debug output comes from in the future.


I'm not aware of a way to do this. It's probably possible, but personally, I would create a custom field formatter (within a custom module).

Once the field formatter is created and the custom module enabled, you can then select it via the admin UI as the image field's formatter on the effected content type(s) display settings (and also for view fields, etc.). You'd want to select it for all displays you want to customize (e.g., full, teaser).

The docs for creating field formatters in D8 can be found here: https://www.drupal.org/docs/8/creating-custom-modules/create-a-custom-field-formatter

For me, the easiest way to create one, is to use Drupal Console to generate the required files and scaffolding (console generate:plugin:fieldformatter). You can either add this to an existing custom module if appropriate, or create a stand-alone custom module that just delivers the field formatter (this option is nice for re-using the formatter across mutltiple projects).

If you don't already have Drupal Console installed, you can download it here: https://drupalconsole.com/

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.