How to Add a Custom Image Size and Use It Properly in WordPress

Customization

December 15, 2025

WordPress automatically generates several image sizes when you upload an image, but real-world projects often need custom image sizes — for cards, thumbnails, hero images, or performance-optimized layouts.

This guide explains how to add a custom image size correctly and, just as importantly, how to use it properly in templates so you avoid blurry images, layout shifts, and wasted bandwidth.

Why You Should Use Custom Image Sizes

Improve performance by serving the right image dimensions
Avoid oversized images being scaled down with CSS
Reduce CLS (Cumulative Layout Shift)
Keep designs consistent across the site
Gain full control over responsive images (srcset)

Relying only on full or large images is one of the most common performance mistakes.

Step 1: Add a Custom Image Size

Add the following code to your child theme’s functions.php or a custom plugin.

add_action( 'after_setup_theme', function() {

  add_image_size(
    'card-thumb', // Name (slug)
    400,          // Width in pixels
    225,          // Height in pixels
    true          // Crop (hard crop)
  );

} );

Parameters Explained

Name: Used when retrieving the image
Width / Height: Final image dimensions
Crop:
- true → exact crop (recommended for UI elements)
- false → proportional resize

Tip: For modern designs, define sizes that match your actual layout — not arbitrary numbers.

Step 2: Make the Image Size Available in the Media Library (Optional)

If you want editors to select the custom size in the media UI:

add_filter( 'image_size_names_choose', function( $sizes ) {

  return array_merge( $sizes, array(
    'card-thumb' => 'Card Thumbnail',
  ) );

} );

This is optional but helpful for non-technical editors.

Step 3: Use the Custom Image Size in Templates

Featured Image (Post Thumbnail)

if ( has_post_thumbnail() ) {
  the_post_thumbnail( 'card-thumb' );
}

This ensures WordPress outputs the correct size and responsive attributes.

Get Image URL Only

Useful for background images or custom markup.

$image_url = get_the_post_thumbnail_url( get_the_ID(), 'card-thumb' );

Get Full Image HTML with Attributes

This method is preferred because it includes srcset, sizes, and loading attributes.

echo wp_get_attachment_image(
  get_post_thumbnail_id(),
  'card-thumb',
  false,
  array(
    'class' => 'card-image',
    'loading' => 'lazy',
  )
);

Step 4: Use Custom Image Sizes in Custom Queries

When looping through posts:

while ( $query->have_posts() ) {
  $query->the_post();

  if ( has_post_thumbnail() ) {
    the_post_thumbnail( 'card-thumb' );
  }
}

Never use full size thumbnails inside loops unless absolutely necessary.

Hard Crop vs Soft Crop (Important)

Hard Crop (`true`)

Exact dimensions
Best for grids, cards, sliders
May cut off edges of images

Soft Crop (`false`)

Preserves aspect ratio
Height may vary
Better for content images

You can also use advanced cropping:

add_image_size( 'hero-wide', 1200, 500, array( 'center', 'top' ) );

Regenerating Thumbnails for Existing Images

Custom image sizes only apply to images uploaded after the size is registered.

To generate sizes for existing images:

Use a thumbnail regeneration plugin
Run regeneration once, then disable/remove the plugin

Do this after finalizing your image size definitions.

Common Mistakes to Avoid

Using full size images in listings
Defining too many unused image sizes
Forgetting to regenerate thumbnails
Setting dimensions that don’t match the layout
Outputting images without width/height attributes

Performance & SEO Best Practices

Match image size to rendered size in CSS
Use wp_get_attachment_image() to get responsive markup
Keep aspect ratios consistent to reduce CLS
Limit the number of custom sizes per project
Combine with lazy-loading and WebP when possible

Where to Put This Code

Best: Child theme or custom plugin
OK for small sites: functions.php
Large projects: Dedicated image setup file (e.g. inc/images.php)

Conclusion

Custom image sizes are a cornerstone of professional WordPress development. When defined intentionally and used correctly, they dramatically improve performance, visual consistency, and Core Web Vitals.

Key takeaway:
Define image sizes based on layout needs — then always use them instead of scaling large images down with CSS.

This small investment pays off across your entire site.

🎨 Want to learn more? Visit our WordPress Customization Hub for tips and advanced techniques.