When I started customizing my Ghost theme, I quickly realized how repetitive image handling could be. Writing <img> tags manually for every post wasn’t scalable — especially if I wanted AVIF/WebP, responsive sizes, and lazy loading.

So, I decided to build a reusable image partial in Ghost using a Handlebars partial. Here’s how it works and how you can adapt it to your own theme.

The Concept

Ghost themes use Handlebars (.hbs) templates. You can define reusable components as partials, then include them anywhere with:

{{> image src=feature_image alt=feature_image_alt class="rounded-xl"}}

This avoids repetition and ensures consistency in your theme design.

The Code Explained

Here’s the reusable image component (partials/image.hbs):

{{!--
Reusable image template for Ghost themes
Params:
  - src (required)
  - alt (optional)
  - class (optional)
  - loading (optional)
  - sizes (optional)
  - default_src_size (optional, defaults to "xl")
  - width / height (optional)
  - decoding (optional)
  - fetchpriority (optional)
  - draggable (optional)
  - animated (optional)
  - excluded_src_sizes (optional, bracket-separated list: e.g. "[xxs][xs]")
Example usage:
{{> image
    src=feature_image
    alt=feature_image_alt
    class="rounded-xl"
    loading="lazy"
    sizes="(max-width: 768px) 100vw, 768px"
    excluded_src_sizes="[xxs][xs]"
}}
--}}

{{#if src}}
  <picture{{#if class}} class="{{class}}"{{/if}}>
      {{#unless animated}}
      <source
          srcset="
              {{^match excluded_src_sizes "~" "[xxs]"}}{{img_url src size="xxs" format="avif"}} 30w,{{/match}}
              {{^match excluded_src_sizes "~" "[xs]"}}{{img_url src size="xs" format="avif"}} 150w,{{/match}}
              {{^match excluded_src_sizes "~" "[s]"}}{{img_url src size="s" format="avif"}} 300w,{{/match}}
              {{^match excluded_src_sizes "~" "[m]"}}{{img_url src size="m" format="avif"}} 720w,{{/match}}
              {{^match excluded_src_sizes "~" "[l]"}}{{img_url src size="l" format="avif"}} 960w,{{/match}}
              {{^match excluded_src_sizes "~" "[xl]"}}{{img_url src size="xl" format="avif"}} 1200w,{{/match}}
              {{^match excluded_src_sizes "~" "[xxl]"}}{{img_url src size="xxl" format="avif"}} 2000w,{{/match}}
              {{img_url src}}"
          {{#if sizes}}sizes="{{sizes}}"{{/if}}
          type="image/avif">
      {{/unless}}

      <source
          srcset="
              {{^match excluded_src_sizes "~" "[xxs]"}}{{img_url src size="xxs" format="webp"}} 30w,{{/match}}
              {{^match excluded_src_sizes "~" "[xs]"}}{{img_url src size="xs" format="webp"}} 150w,{{/match}}
              {{^match excluded_src_sizes "~" "[s]"}}{{img_url src size="s" format="webp"}} 300w,{{/match}}
              {{^match excluded_src_sizes "~" "[m]"}}{{img_url src size="m" format="webp"}} 720w,{{/match}}
              {{^match excluded_src_sizes "~" "[l]"}}{{img_url src size="l" format="webp"}} 960w,{{/match}}
              {{^match excluded_src_sizes "~" "[xl]"}}{{img_url src size="xl" format="webp"}} 1200w,{{/match}}
              {{^match excluded_src_sizes "~" "[xxl]"}}{{img_url src size="xxl" format="webp"}} 2000w,{{/match}}
              {{img_url src}}"
          {{#if sizes}}sizes="{{sizes}}"{{/if}}
          type="image/webp">

      <img
          srcset="
              {{^match excluded_src_sizes "~" "[xxs]"}}{{img_url src size="xxs"}} 30w,{{/match}}
              {{^match excluded_src_sizes "~" "[xs]"}}{{img_url src size="xs"}} 150w,{{/match}}
              {{^match excluded_src_sizes "~" "[s]"}}{{img_url src size="s"}} 300w,{{/match}}
              {{^match excluded_src_sizes "~" "[m]"}}{{img_url src size="m"}} 720w,{{/match}}
              {{^match excluded_src_sizes "~" "[l]"}}{{img_url src size="l"}} 960w,{{/match}}
              {{^match excluded_src_sizes "~" "[xl]"}}{{img_url src size="xl"}} 1200w,{{/match}}
              {{^match excluded_src_sizes "~" "[xxl]"}}{{img_url src size="xxl"}} 2000w,{{/match}}
              {{img_url src}}"
          {{#if sizes}}sizes="{{sizes}}"{{/if}}
          src="{{#if default_src_size}}{{img_url src size=default_src_size}}{{else}}{{img_url src size="xl"}}{{/if}}"
          {{#if alt}}alt="{{alt}}"{{/if}}
          {{#if class}}class="{{class}}"{{/if}}
          {{#if loading}}loading="{{loading}}"{{/if}}
          {{#if decoding}}decoding="{{decoding}}"{{/if}}
          {{#if fetchpriority}}fetchpriority="{{fetchpriority}}"{{/if}}
          {{#if draggable}}draggable="{{draggable}}"{{/if}}
          {{#if width}}width="{{width}}"{{/if}}
          {{#if height}}height="{{height}}"{{/if}}>
  </picture>
{{/if}}

It uses the <picture> tag to provide multiple formats (AVIF, WebP, fallback JPG/PNG).
Ghost automatically generates responsive image sizes, so your visitors only download what they need.

<picture>: The Picture element - HTML | MDN

The <picture> HTML element contains zero or more <source> elements and one <img> element to offer alternative versions of an image for different display/device scenarios.

MDN

Optional Parameters

The snippet supports:

excluded_src_sizes → skip certain image sizes
sizes → control how images behave across screen widths
loading, fetchpriority, and decoding → performance hints
animated → skip AVIF for GIFs

You can call it anywhere in your theme, for example inside post.hbs or card.hbs.

Why This Matters

A reusable image component:

Simplifies your theme code
Improves Lighthouse performance scores
Ensures every image uses best practices automatically

Once you set it up, you never have to worry about srcset again.

Personal Reflection

At first, I thought performance tweaks like this were overkill. But after seeing the difference in loading speed — especially on mobile — I realized small details add up.
Coding is like brewing coffee: take time, refine the process, and the result feels rewarding.

Building a Reusable Image Partial for `Ghost` Themes

Learn how to build a reusable, optimized image partial in Ghost using Handlebars. We’ll explore how it works, how to customize it, and why it matters for performance.