Fitted Image

Overview

A container‑filling image block with cover or contain fitting options, plus controls for aspect ratio, padding, background color, overlaid gradients, and linking.

• Block name: method/fitted-image
• Category: method-component-blocks
• Supports: align (wide, full)
• Uses context: postId
• Render type: Dynamic (PHP render_callback)
• Inner blocks: No

Usage

The Fitted Image block renders an image that fills its container using CSS object‑fit, with optional aspect ratio enforcement, shade overlays, and link wrapping. It is especially useful inside grid items and query loop templates where consistent image sizing is needed.

Key features:

• Shade overlay: Apply a color or gradient overlay on top of the image.
• Featured Image mode: Toggle “Use Featured Image” to pull the image from the current post’s featured image. Useful in query loop / archive templates.
• Link to Post: When using featured images, optionally link the entire block to the source post. The block renders even without an image (useful for archive grid placeholders).
• Aspect Ratio: Choose from preset aspect ratios or use the image’s natural dimensions.

Attributes

responsiveSettings Structure

• aspectUses — "ratio" to use a preset, empty for natural image dimensions
• aspectRatio — Preset string like "-16-9", "-4-3", "-1-1"
• bgImgSize — WordPress image size to use (thumbnail, medium, large, full)
• bgDisplaySize — CSS object‑fit modifier class
• zeroHeight — collapses the block’s vertical footprint to zero (height: 0; overflow: visible) while the image stays visible, for overlap layouts; false on a non-base breakpoint restores normal flow there

Control Sets

Additional Inspector controls, at the top of the Image Options panel: “Enable Lightbox” (CheckboxControl, offered when neither Link to Post nor a toolbar link is set), “Use Featured Image” (CheckboxControl), “Link to Post” (CheckboxControl, shown when the featured image is enabled and neither the lightbox nor a toolbar link is active).

Data

• Post context: The block uses WordPress’s postId context to access the current post’s featured image via get_the_post_thumbnail().
• Image fallback chain: When useFeaturedImage is enabled, the block first tries the featured image, then falls back to bgImg if no featured image exists, then returns nothing (unless linkToPost is set, which forces rendering).

Frontend Rendering

<!-- Without link -->
<div class="method-block-fitted-image" id="method-{id}">
  <div class="method-block-content">
    <div class="method-block-shade"> </div>
    <div class="method-fit-img-container {method-ratio method-ratio-X-Y?}">
      <img class="method-fit-img {size-class?}" src="..." alt="..." />
    </div>
  </div>
</div>

<!-- With link or linkToPost -->
<a target="_self|_blank" href="{url}" class="method-block-fitted-image" id="method-{id}">
  <!-- same inner structure -->
</a>

With lightbox on, the wrapper is an <a class="method-block-fitted-image method-lightbox-trigger"> carrying the attributes from method_get_lightbox_attributes() for whichever image was rendered — the selected image or, with Use Featured Image, the post’s thumbnail — so without the view script (frontend.js, built from lib/blocks/utils/lightbox.js) it degrades to a plain link to the full-size file. The lightbox wrapper takes precedence over the Link to Post and toolbar-link wrappers.

The aspect ratio is applied via CSS classes: method-ratio enables the ratio system and method-ratio-{w}-{h} (e.g., method-ratio-16-9) sets the specific ratio using CSS aspect-ratio or padding‑based techniques.

Filters

This block does not currently expose dedicated PHP filters. Image size registration and aspect ratio classes are controlled by the theme’s global stylesheet.

Changelog