ACF Image Field Renderer — Alt Text Fallback PHP

Raw get_sub_field() with a manual <img> tag works. The problem is not correctness — it’s discoverability and consistency. An ACF Image field returning an Image ID requires three separate function calls (get_sub_field(), wp_get_attachment_image_src(), get_post_meta()) before you can render a tag. Every flexible layout repeats the same pattern. Forget one esc_url() and you have an XSS vector. Add a new registered image size and you need to update every wp_get_attachment_image_src() call individually. Change your lazy loading strategy and you’re find-and-replacing across twenty template files.

theme_render_image() solves the consistency problem. One function accepts an image ID + size and returns a complete, escaped <img> tag. The output runs through esc_url() on the src and esc_attr() on every other attribute — three escaping calls total. If the attachment doesn’t exist (deleted from the Media Library after the field was saved), wp_get_attachment_image_src() returns false and the function returns an empty string — no broken image icon, no console error. Width and height from wp_get_attachment_image_src() are included so the browser reserves the correct aspect ratio before the image loads, eliminating Cumulative Layout Shift.

The four-level alt fallback chain is the main value-add of this component. Each level is checked in priority order. Level 1 — ACF custom alt field: If the developer passes an acf_alt_field name (e.g. 'hero_image_alt'), the function calls get_field( $acf_alt_field, $image_id ) to read a hand-crafted alt text stored on the attachment. This is the most intentional source — the editor wrote it specifically for this image in this context — so it wins. Level 2 — WordPress attachment alt: If no custom ACF alt field was passed, or it returned empty, the function falls back to get_post_meta(..., '_wp_attachment_image_alt', true ) — the standard alt text field every image gets in the Media Library. Level 3 — Attachment post title: If the Media Library alt field is also empty (common — many editors skip it), the function uses get_the_title( $image_id ). The attachment title is typically the original filename or a descriptive label, making it a reasonable last-resort alt text. Level 4 — Empty string: If all three sources are empty, the alt attribute is "". This is valid HTML (the attribute exists, its value is empty) and signals to screen readers that the image is decorative. It is never null — passing null to esc_attr() triggers a deprecation warning in PHP 8.1+.

srcset and sizes make the image responsive without any manual breakpoint configuration. wp_get_attachment_image_srcset() looks at every registered image size in WordPress (core sizes plus any added via add_image_size()) and finds the closest match to each of the standard srcset width descriptors (300w, 600w, 900w, etc.). For a 2000px wide uploaded image registered at large (1024px), the browser might receive: srcset="img-300x200.jpg 300w, img-600x400.jpg 600w, img-1024x683.jpg 1024w, img-1536x1024.jpg 1536w, img-2000x1333.jpg 2000w". wp_get_attachment_image_sizes() outputs a default sizes string — typically (max-width: {size}px) 100vw, {size}px — which tells the browser: “At viewports narrower than the image’s intrinsic width, this image fills 100% of the viewport width. At wider viewports, it’s capped at its intrinsic width.” The browser then picks the smallest srcset variant that covers the calculated slot width. You can override the sizes string per layout by passing a custom one.

The production component combines all five layers into a single call. wp_parse_args() merges the caller’s options with defaults so optional arguments don’t need to be passed every time. $loading is validated against a whitelist (lazy | eager) — invalid strings fall back to 'lazy' so a typo doesn’t prevent all images from loading. decoding="async" tells the browser to decode the image off the main thread, improving paint timing — this is safe on all modern browsers and is a set-and-forget attribute. The $fallback_url parameter provides an image placeholder when the attachment has been deleted — useful during development when content and media are out of sync.

Create inc/theme-image.php with the Step 5 code. In functions.php, add the require statement at the top of the file — before any template includes — so the helper is available everywhere:

require_once get_template_directory() . '/inc/theme-image.php';

Set up your ACF Image fields. In each field group, add an Image field with Return Format → Image ID — this is the format theme_render_image() expects. If you want a custom alt text per image, add a second Text field to the same field group with a descriptive name like hero_image_alt. Example field group:

Field 1: hero_image   → Type: Image  → Return Format: Image IDnField 2: hero_image_alt → Type: Text  → Label: "Alt text override"

The second field is optional — if you skip it, the function falls through to WordPress attachment alt and post title.

Replace raw <img> tags in your flexible content templates. In template-parts/flexible/hero.php, change:

// Before — 6 lines of manual HTML per image.n$img_id = get_sub_field( 'hero_image' );nif ( $img_id ):n    $img = wp_get_attachment_image_src( $img_id, 'large' );n    ?>n    <img src="<?php echo esc_url( $img[0] ); ?>"n         alt="<?php echo esc_attr( get_post_meta( $img_id, '_wp_attachment_image_alt', true ) ); ?>" />n    <?phpnendif;nn// After — 1 line.necho theme_render_image( (int) get_sub_field( 'hero_image' ), 'large', [n    'acf_alt_field' => 'hero_image_alt',n    'loading'       => 'eager',n    'class'         => 'hero__image',n] );

The field name in get_sub_field() stays the same. You’re only changing how the result is rendered.

If your theme already has get_sub_field() image calls in many flexible layouts, replace them incrementally. Start with the layouts you touch most — hero, card grids, featured images. Test each one by viewing the page and checking that the <img> tag in the source includes srcset, sizes, loading="lazy", and a non-empty alt attribute. Leave the rest for when you edit those templates. There is no migration cost — old get_sub_field() + manual <img> calls continue to work alongside theme_render_image().

Add a custom sizes override for specific layouts. The default sizes string works for full-width heroes but not for card grids where images sit at 33% width. Add a sizes argument that replaces the auto-generated one:

$args['sizes'] = $args['sizes'] ?? '';nn// ... in the sprintf, use the custom sizes if provided:n$sizes_attr = $args['sizes'] ?: wp_get_attachment_image_sizes( $image_id, $size );nn// Usage for a 3-column card grid:necho theme_render_image( $image_id, 'card', [n    'sizes' => '(min-width: 768px) 33vw, 100vw',n] );

This tells the browser: “At 768px+, this card image fills 33% of the viewport. Below that, it fills 100%.” The browser then picks the smallest srcset variant that covers the calculated pixel width.

Add a <picture> wrapper for art direction. If your hero image is cropped differently on mobile (tall on phone, wide on desktop), you need a <picture> element with <source> media queries — not just a srcset:

function theme_render_picture( int $image_id, array $args = [] ): string {n    $args = wp_parse_args( $args, [n        'mobile_size'  => 'hero-mobile',n        'desktop_size' => 'hero-desktop',n        'breakpoint'   => '768px',n    ] );nn    $mobile  = wp_get_attachment_image_src( $image_id, $args['mobile_size'] );n    $desktop = wp_get_attachment_image_src( $image_id, $args['desktop_size'] );n    if ( ! $mobile || ! $desktop ) return '';nn    $alt = theme_image_alt( $image_id, $args['acf_alt_field'] ?? '' );nn    return sprintf(n        '<picture><source srcset="%s" media="(max-width: %s)" /><img src="%s" alt="%s" loading="lazy" decoding="async" /></picture>',n        esc_url( $mobile[0] ), esc_attr( $args['breakpoint'] ),n        esc_url( $desktop[0] ), esc_attr( $alt )n    );n}

Add a low-quality image placeholder (LQIP) system for perceived performance. Generate a tiny blurred version of each uploaded image and show it while the full image loads:

// Register a micro thumbnail size.nadd_image_size( 'lqip', 20, 20, true );nn// In theme_render_image(), add:nif ( $args['lqip'] ) {n    $lqip_src = wp_get_attachment_image_url( $image_id, 'lqip' );n    if ( $lqip_src ) {n        $attr .= ' style="background-image: url(' . esc_url( $lqip_src ) . '); background-size: cover;"';n    }n}

The 20px thumbnail is typically under 500 bytes — it loads instantly and gives the user a sense of content before the full-resolution image finishes downloading.

Extract the alt text logic into a separate theme_image_alt() helper. If you need alt text outside of the render function — e.g. for an ARIA label or an Open Graph meta tag — the alt chain is duplicated:

function theme_image_alt( int $image_id, string $acf_alt_field = '' ): string {n    $alt = '';n    if ( $acf_alt_field ) {n        $alt = (string) get_field( $acf_alt_field, $image_id ); // ACF field type: Textn    }n    if ( empty( $alt ) ) {n        $alt = (string) get_post_meta( $image_id, '_wp_attachment_image_alt', true );n    }n    if ( empty( $alt ) ) {n        $alt = (string) get_the_title( $image_id );n    }n    return $alt;n}nn// Then theme_render_image() calls theme_image_alt() instead of inline logic.n// Usage anywhere:n$og_image_alt = theme_image_alt( $hero_id, 'hero_image_alt' );