Use A Named Size#
Use image_size() when an image should use a named WordPress image size:
<img src="{{ hero_image | image_size("medium") }}" alt="{{ hero_image.alt }}">The size name can be a WordPress size such as thumbnail, medium, or large, or a custom size registered by the theme or a plugin.
If you already wrote .url, the modifier can still read the original image value:
<img src="{{ hero_image.url | image_size("thumbnail") }}" alt="{{ hero_image.alt }}">Inside gallery loops, use the same modifier on the current image:
{{ gallery }} <img src="{{ url | image_size("thumbnail") }}" alt="{{ alt }}">{{ /gallery }}If the requested size is not available for an image yet, TemplateX falls back to the original image URL.
Use The Original Upload#
Use original_image when you need the original uploaded file instead of a generated WordPress size:
<img src="{{ hero_image | original_image }}" alt="{{ hero_image.alt }}">This is useful when WordPress has created a scaled full-size file but you need the actual upload. The modifier works best with media values that include an attachment ID, such as ACF image fields, gallery items, or featured_image. If TemplateX only has a plain URL, it returns that URL.
Convert To WebP Or AVIF#
Use webp or avif when an image URL should point to a converted copy:
<img src="{{ hero_image | webp }}" alt="{{ hero_image.alt }}">The format modifier can be combined with image_size(). Put the size first, then the format:
<img src="{{ hero_image | image_size("medium") | avif }}" alt="{{ hero_image.alt }}">TemplateX converts the final image file to the requested format and returns the converted file URL. The compiled theme PHP handles this at runtime, so it does not depend on bun run dev, Vite, or another asset watcher. Once the converted file exists, TemplateX reuses it instead of converting it again.
If WordPress cannot write the converted file, the server does not support the requested format, or the image URL points to an external host, TemplateX falls back to the original image URL.
Optimize Existing Images#
The webp and avif modifiers can create converted files the first time a template asks for them. For existing media libraries, you can compress those files ahead of time.
Go to TemplateX > Settings > Extensions and open Options in the Optimize Images row. Choose:
- Quality: Smallest Size, Balanced, or Best Quality
- Format: WebP or AVIF
- Uploaded Images: Manual or Auto-Convert
Use Bulk Compress to process existing image attachments in small batches. For each attachment, TemplateX checks the original file and the generated WordPress size files, then creates missing files in the selected format beside them.
When the selected format changes from WebP to AVIF or from AVIF to WebP, Bulk Compress removes the other optimized sidecar format for each processed image. Existing converted files in the selected format are kept. Original uploads are not replaced, attachment IDs do not change, and media URLs keep working. If the server image editor cannot create a requested format, TemplateX skips that file and keeps the original image URL as the runtime fallback.
Choose Auto-Convert for Uploaded Images when new images should get the selected optimized format automatically after WordPress finishes generating their image sizes. TemplateX starts that work in the background immediately so the upload screen does not wait for every conversion before responding. If attachment details load before the background job finishes, TemplateX completes that image's queued conversion before returning the optimized status. This uses the same sidecar-file approach as Bulk Compress.
On the frontend, TemplateX serves the selected optimized sidecar when the browser advertises support for that format. If the exact sidecar for a local upload or generated WordPress size is missing but the source image still exists, TemplateX creates that sidecar before returning the URL. Native WordPress attachment images, responsive srcset sources, and images rendered through post content can be rewritten from .png, .jpg, or .jpeg to .webp or .avif. In browser DevTools, a delivered optimized image should show a .webp or .avif request URL and a matching Content-Type.
Hard-coded upload URLs in template files are not rewritten unless they pass through a TemplateX media value or format modifier. Use {{ image | webp }} or {{ image | avif }} when a specific template URL should force a format.
The Media Library shows an Optimized column in list view. Converted images show WebP ready or AVIF ready badges with compact details such as 8 files, 3 MB to 1 MB, and 67% saved. The full original-size, compressed-size, and file-breakdown details are available in the badge title. Images waiting for background conversion can show Queued in list view. Images without optimized sidecars show Original only. Attachment details load this status after the modal opens so the preview does not wait on file checks, and they resolve a queued conversion for that attachment before showing the final badge.
Add A Custom Size#
Go to Settings > Media in WordPress. TemplateX adds custom image size rows to the native Image sizes list.
Add a name, maximum width, maximum height, and whether WordPress should crop the image to exact dimensions. Save the Media settings page.
TemplateX turns the name into a snake_case key for templates:
<img src="{{ portrait | image_size("card_image") }}" alt="{{ portrait.alt }}">For example, a size named Card Image is available as card_image.
How Generation Works#
WordPress creates generated image files when an image is uploaded. After you save a new custom size, future uploads automatically get that size.
Existing uploads are different. WordPress does not go back through old images automatically. After adding or changing a size, save the Media settings page, then use Regenerate image sizes in the same section to update older uploads.
The regenerate button works in small batches. While it runs, it shows progress. When it finishes, it shows how many images were regenerated.
Clean Up Removed Sizes#
If you remove a custom size later, save the Media settings page, then use Clean up unused sizes.
Cleanup removes old generated files for sizes WordPress no longer has registered. It keeps the original upload and any generated file that is still used by an active WordPress image size.