Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsRegister a named size with add_image_size(), request that name when rendering an image, and regenerate thumbnails for media uploaded before the change. Your crop setting determines whether WordPress preserves the whole image or cuts it to a fixed frame.
1. Register the custom image size
WordPress registers additional renditions with add_image_size(). Its signature is add_image_size( string $name, int $width, int $height, bool|array $crop = false ). Give the size a unique name and explicit, positive dimensions.
add_action( 'after_setup_theme', function () {
add_image_size( 'article-card', 640, 360, true );
} );This example creates a named 640×360 rendition called article-card. The numbers are example values: match them to the actual slot in your theme rather than treating them as universal recommendations.
Where the code belongs
- Theme-specific layout: register the size in the theme’s setup code, commonly on
after_setup_theme. - Reusable feature: put registration in a plugin if the size must remain available when the site changes themes.
Registration alone does not make WordPress use the file. You must request the named size when outputting an image.
2. Choose proportional resizing or a hard crop
The fourth argument controls how WordPress fits the source image to the requested dimensions.
| Setting | Result | Best fit | Main risk |
|---|---|---|---|
false (default) |
Scales proportionally, preserving the entire image. The resulting file can be smaller than one or both requested dimensions when the source aspect ratio differs. | Photography, product images, or any content where no subject may be cut off. | Cards in a rigid grid may have different displayed proportions. |
true |
Hard-crops to the requested width and height, using a centered crop. | Uniform cards, hero tiles, avatars, and other fixed-ratio slots. | Important faces, text, or objects can be removed. |
| Crop-position array | Hard-crops while choosing the crop origin. Horizontal values are left, center, or right; vertical values are top, center, or bottom. |
Layouts where the subject consistently sits away from the center. | A fixed position can fail on images with different compositions. |
add_image_size( 'portrait-card', 480, 640, array( 'center', 'top' ) );Use the crop-position array only when the design calls for a predictable focal area. The crop behavior and accepted values are documented in the add_image_size() reference.
3. Make the theme support featured images
If the size will be used with featured images, the active theme must declare thumbnail support:
Rank #2
add_action( 'after_setup_theme', function () {
add_theme_support( 'post-thumbnails' );
add_image_size( 'article-card', 640, 360, true );
} );The support declaration enables featured-image UI and functions; it does not select your custom size automatically.
4. Request the custom size when rendering
Featured image in a loop or template
the_post_thumbnail( 'article-card' );The size name must exactly match the name used during registration. If the requested rendition is unavailable, WordPress may fall back to another available image representation.
Attachment image by ID
echo wp_get_attachment_image( $attachment_id, 'article-card' );wp_get_attachment_image() returns the image element with WordPress-managed dimensions and attributes for the attachment ID.
Rank #3
Let editors choose the size in the Media interface
Most templates should choose a size in code. If administrators need to select the rendition in an image picker, add a readable label through the image_size_names_choose filter:
add_filter( 'image_size_names_choose', function ( $sizes ) {
$sizes['article-card'] = 'Article card (640×360)';
return $sizes;
} );Registering a size does not require adding this label; it is only for an editor-facing choice.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →5. Understand which sizes WordPress generates
The intermediate_image_sizes filter exposes the list of intermediate size names. WordPress’s documented defaults include thumbnail, medium, medium_large, and large, alongside registered custom sizes.
To control the sizes generated during an upload, use intermediate_image_sizes_advanced. The filter receives the size array, image metadata, and attachment ID, allowing a plugin or site-specific integration to remove or alter generated sizes. Use it cautiously: removing a size that a template requests can leave that template without its intended rendition.
6. Regenerate sizes for existing media
Adding PHP code affects future processing; existing attachments do not automatically gain the new file. Regenerate their metadata and intermediate images after registering the size.
WP-CLI method
From the WordPress installation directory, the official command is:
wp media regenerate --image_size=article-cardThe wp media regenerate documentation also defines these useful options:
--only-missingprocesses only sizes that are absent.--skip-deleteretains existing files that are no longer registered.--delete-unknownremoves thumbnails for sizes no longer registered.
For a first pass on a live site, target the new size and consider --only-missing. Treat deletion options as maintenance operations: --skip-delete favors retention, while --delete-unknown can remove files still referenced by old content or integrations.
wp media regenerate --image_size=article-card --only-missingProgrammatic regeneration
WordPress’s wp_generate_attachment_metadata() reference describes regenerating intermediate files and updating the attachment with wp_update_attachment_metadata(). A simplified pattern is:
$file = get_attached_file( $attachment_id );
$metadata = wp_generate_attachment_metadata( $attachment_id, $file );
wp_update_attachment_metadata( $attachment_id, $metadata );Run this in a controlled batch rather than on every page request. The metadata function does not check or delete previously generated intermediate files, so it is not a substitute for deciding how old, unregistered files should be handled.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match7. Check source dimensions and output availability
WordPress generates an intermediate size only when the requested dimensions are smaller than the source image, as described in the wp_generate_attachment_metadata() documentation. A small original cannot be enlarged into every configured rendition. Consequently:
- Use source images large enough for the largest layout slot.
- Expect some attachments to lack a requested custom file.
- Test templates with both large and small uploads, including images with unusual aspect ratios.
8. Do not confuse custom sizes with the featured-thumbnail size
set_post_thumbnail_size() registers the dedicated post-thumbnail size. It is useful when a theme wants to define that specific featured-image size, but it does not resize existing featured images. Existing attachments still require regeneration after dimensions or crop behavior change.
Quick Recap
Practical implementation checklist
- Choose a unique, descriptive size name tied to a real template slot.
- Set explicit width and height values; leaving dimensions at zero can cause unwanted behavior.
- Decide whether preserving the full image or enforcing a fixed crop matters more.
- Register the size in theme setup or in a plugin according to ownership.
- Request the name with
the_post_thumbnail()orwp_get_attachment_image(). - Add an
image_size_names_chooselabel only when editors need to select it. - Regenerate older attachments, preferably targeting the new size first.
- Verify that original images are large enough and that crops keep important subjects visible.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
