Skip to main content

Image

Image objects represent image attachments in WordPress. There's no image root variable; you get an Image whenever an image-mime attachment is in scope.

How you get an Image object:

{{ post.thumbnail }}              <!-- Featured image -->
{{ site.icon }}                   <!-- Site icon -->
{{ get_image(123) }}              <!-- By attachment ID -->

Image inherits everything from Attachment and Post — id, title, slug, link, dates, author, parent, meta, edit_link, raw post_* fields, etc. The fields below are image-only.

All Fields​

FieldArgumentsReturnsDescription
srcsizestringImage URL
srcsetsizestring | nullSrcset attribute value (null if no metadata)
img_sizessizestring | nullSizes attribute value (null if no metadata)
width—int | nullWidth in pixels (null if unknown)
height—int | nullHeight in pixels (null if unknown)
aspect—float | nullAspect ratio (null if unknown)
alt—stringAlt text (always a string — '' for decorative images)

Image Source​

The src field accepts an optional size parameter:

{{ post.thumbnail.src }}                    <!-- Full size URL -->
{{ post.thumbnail.src('thumbnail') }}       <!-- 150x150 -->
{{ post.thumbnail.src('medium') }}          <!-- 300px max -->
{{ post.thumbnail.src('medium_large') }}    <!-- 768px max -->
{{ post.thumbnail.src('large') }}           <!-- 1024px max -->
{{ post.thumbnail.src('custom-size') }}     <!-- Custom registered size -->

srcset, img_sizes, width, height, and aspect return null when the image has no metadata (e.g. SVGs, externally hosted, or files where dimensions weren't captured) — pair them with ?? to fall back gracefully.

alt is always a string. For decorative images (or when no alt is set) it returns '' — matches the <img alt=""> decorative-image convention, so it's safe to output directly.

Common Patterns​

Responsive image​

<img
  src="{{ post.thumbnail.src('large') }}"
  srcset="{{ post.thumbnail.srcset }}"
  sizes="{{ post.thumbnail.img_sizes }}"
  alt="{{ post.thumbnail.alt }}"
  width="{{ post.thumbnail.width }}"
  height="{{ post.thumbnail.height }}"
>
{{ post.thumbnail.src('large') ?? '/default-image.jpg' }}

Alt text with fallback​

{{ post.thumbnail.alt ?: post.thumbnail.title ?: 'Image' }}

(Note: alt is always a string, so use ?: to also fall back on the empty decorative-image string.)

Site icon​

{{ site.icon.src('thumbnail') }}