WordPress add_image_size Example: Register a Custom Theme Image Size

Last reviewed: April 28, 2026

Theme image output gets inconsistent fast when templates mix arbitrary dimensions, full-size uploads, and one-off cropping logic. add_image_size() gives a theme a stable image vocabulary so cards, hero media, and archive thumbnails all render with predictable sizes.

This guide shows how to register a custom image size and use it safely in a theme.

Register the custom size during theme setup

<?php
add_action( 'after_setup_theme', 'vulnwp_register_image_sizes' );

function vulnwp_register_image_sizes() {
	add_theme_support( 'post-thumbnails' );
	add_image_size( 'vulnwp-card', 960, 640, true );
}

Registering on after_setup_theme keeps the size definition aligned with theme support and makes the intent obvious.

Render the new size in templates

if ( has_post_thumbnail() ) {
	the_post_thumbnail(
		'vulnwp-card',
		array(
			'class' => 'archive-card__image',
		)
	);
}

Once the size is registered, template code can request it by name instead of repeating width and height decisions everywhere.

Expose the size in the media UI when editors need it

add_filter( 'image_size_names_choose', 'vulnwp_add_editor_image_size' );

function vulnwp_add_editor_image_size( $sizes ) {
	return array_merge(
		$sizes,
		array(
			'vulnwp-card' => __( 'Archive Card', 'vulnwp' ),
		)
	);
}

This is useful when editors insert media manually and the theme wants the same named size available in the admin experience.

Remember that new sizes apply to uploads going forward

Registering a new image size does not retroactively generate that size for older uploads on its own. Existing media may need regeneration before templates can rely on the new variant across the full library.

Production checklist

• Register custom sizes on after_setup_theme.
• Enable featured-image support when the theme needs thumbnail output.
• Name the size after a UI role, not an arbitrary number string.
• Use the registered size consistently in templates.
• Expose the size in the editor only if the editorial workflow needs it.
• Plan for older media that may not yet have the generated variant.

Common mistakes

• Registering the size too late. Theme setup is the correct place for image definitions.
• Naming sizes after one temporary layout. Role-based names survive redesigns better.
• Assuming older uploads already have the new size. They often do not.
• Hardcoding full-size images in templates anyway. That defeats the purpose of the named size.
• Using inconsistent crop behavior across similar components. Cards and archives should feel deliberate.

Related reading

If the theme renders attachment markup directly, pair this with the wp_get_attachment_image guide. If the upload path itself needs inspection during custom media workflows, see the wp_upload_dir article.

References and further reading

• WordPress Code Reference: add_image_size()
• WordPress Theme Handbook: Featured Images and Post Thumbnails
• WordPress Code Reference: image_size_names_choose