WordPress wp_get_attachment_image Example: Render Media Safely in Themes

Last reviewed: April 26, 2026

Rendering image attachments by hand with custom <img> markup usually looks simple, but it often throws away responsive attributes that WordPress can generate automatically. The result is worse performance, weaker accessibility, and more manual attribute handling than necessary.

This guide shows how to use wp_get_attachment_image() so themes and plugins render attachment images with proper size handling, alt text, and loading hints.

Render an attachment with a registered size

<?php
echo wp_get_attachment_image(
	$attachment_id,
	'large',
	false,
	array(
		'class' => 'hero-media',
	)
);

Using a registered size is better than guessing dimensions manually. WordPress can then generate the correct image variant, classes, srcset, and sizes metadata automatically.

Override alt text or loading attributes when needed

echo wp_get_attachment_image(
	$attachment_id,
	'medium_large',
	false,
	array(
		'alt'           => 'Operations dashboard screenshot',
		'loading'       => 'lazy',
		'fetchpriority' => 'low',
	)
);

The attribute array lets the template stay deliberate without dropping down to handcrafted <img> tags for every variant.

Check for missing attachments

$image_html = wp_get_attachment_image( $attachment_id, 'thumbnail' );

if ( '' === $image_html ) {
	return;
}

echo $image_html;

The function returns an empty string on failure. Handle that case cleanly instead of assuming the attachment ID is always valid.

Why this is safer than manual image HTML

• WordPress can add responsive srcset and sizes attributes.
• Theme code stays shorter and less error-prone.
• Attachment alt text can flow from the media library instead of being rebuilt ad hoc.
• Loading and decoding hints can be controlled through the attribute array.

Production checklist

• Prefer registered image sizes over arbitrary width/height arrays.
• Handle the empty-string failure case.
• Set or review alt text intentionally.
• Use the attribute array for class, loading, decoding, and fetch priority overrides.
• Do not rebuild image markup manually unless the output truly requires it.
• Test large media blocks on mobile and desktop layouts.

Common mistakes

• Passing the parent post ID instead of the attachment ID. The helper expects an attachment.
• Ignoring alt text. Media library metadata still needs editorial review.
• Hardcoding full image URLs in templates. That fights WordPress image optimization.
• Using unregistered custom dimensions everywhere. Registered sizes are easier to optimize and reason about.
• Forcing eager loading broadly. Reserve high-priority loading for truly critical images.

Related reading

If the attachment is created by plugin uploads, pair this with the media upload guide. If the image is displayed as a featured visual in templates, keep the output aligned with the template hierarchy article.

References and further reading

• WordPress Code Reference: wp_get_attachment_image()
• WordPress Code Reference: wp_get_attachment_image_src()
• WordPress Theme Handbook: Images