WordPress Hero Image Size: A Complete Guide to Dimensions, Cropping, and Responsive Delivery
There is no universal WordPress hero image size. Choose dimensions from your theme’s hero container, aspect ratio, crop behavior, and responsive image setup.
There is no single WordPress-wide hero image size. The correct dimensions depend on whether your theme uses a featured image, Cover block, or regular Image block; the hero container’s aspect ratio; and how the theme crops and serves responsive images.
Start with the active theme or template’s documented featured-image size when one exists. Then choose an image with enough resolution for the largest display, match the container’s aspect ratio, and set a focal point that survives desktop and mobile crops.
What “hero image size” means in WordPress
“Hero image” describes a layout role, not a built-in WordPress image-size preset. WordPress provides image variants such as Thumbnail, Medium, Medium Large, Large, and Full Size, while themes and plugins can register additional sizes with functions such as add_image_size().
The documented default maximums are:
| WordPress size | Documented default | What it means |
|---|---|---|
| Thumbnail | 150 × 150 px | Small square variant, normally cropped |
| Medium | 300 × 300 px | Medium variant, constrained by the configured dimensions |
| Medium Large | 768 px wide | Width limit with no height limit |
| Large | 1024 × 1024 px | Large variant constrained by configured dimensions |
| Full | Original processed upload | Use only when the displayed context needs it |
These are generated variants, not universal hero recommendations. Your site settings, theme registrations, and plugins can change which files are available.
Find the right dimensions for your layout
- Identify the display path. Check whether the hero is a theme featured image, a Cover block background, or an Image block.
- Inspect the container. Measure the desktop and mobile hero width and height, or calculate the aspect ratio from the template CSS.
- Check theme documentation. Classic-style themes often publish a recommended featured-image width. For example, Twenty Twenty-One documents featured images at 610 px wide or larger; that guidance applies to that theme only.
- Choose source dimensions for the largest intended display. Leave enough resolution for high-density screens without uploading an unnecessarily huge original.
- Preview narrow and wide crops. Keep faces, products, and other important subjects away from edges that may be removed.
Without the active theme and template, nobody can give a reliable universal pixel number. The layout determines the answer.
Featured image, Cover block, or Image block?
Theme featured image
The theme controls the markup, selected sub-size, aspect ratio, and crop. Read the theme documentation and inspect the template or block pattern. A theme may request a custom registered size rather than the WordPress Large variant.
Cover block
A Cover block fills its area by cropping the image. Use the focal-point control to keep the subject visible. Cover is suitable when edge cropping is acceptable and the hero must maintain a fixed visual shape.
Image block
An Image block can preserve the full image with Contain, or fill a box with Cover-style cropping when the design calls for it. WordPress recommends leaving width and height set to Auto in most cases. See the Image block documentation.
| Display method | Best when | Main risk |
|---|---|---|
| Featured image | The theme owns the article header | Theme-specific crop or size rules |
| Cover block | You need a full-bleed hero shape | Important content can be cropped |
| Image block | You need explicit image controls | Layout may not fill the hero container |
Aspect ratio and cropping
Match the source image to the hero container’s ratio when possible. A wide desktop hero may crop substantially on a tall mobile layout, so test both states.
- Cover: fills the box and crops overflow.
- Contain: shows the entire image but can leave empty space.
- Focal point: shifts the crop toward the subject.
- Auto dimensions: preserve intrinsic proportions and reduce distortion.
Do not place essential text, faces, or product edges at the extreme borders. If the image contains text that must remain readable, use an Image block or separate HTML text instead of relying on a cropped background.
Responsive images and generated sub-sizes
WordPress can create multiple image sub-sizes and emit responsive markup so the browser can select a suitable file for the current display. The responsive-images documentation describes how srcset and sizes support this behavior.
For example, a 1500 × 706 upload is an example used in WordPress documentation to explain responsive delivery. It is not a universal hero standard. A phone may receive a smaller generated variant while a wide desktop receives a larger one.
<img
src="hero-1500x706.jpg"
srcset="hero-768x362.jpg 768w,
hero-1024x482.jpg 1024w,
hero-1500x706.jpg 1500w"
sizes="(max-width: 768px) 100vw, 1200px"
width="1500"
height="706"
alt="Dashboard showing monthly sales trends"
>In normal WordPress content, let WordPress generate this markup rather than hand-writing it. Verify the final HTML in your browser’s inspector and confirm that mobile devices are not downloading the largest file unnecessarily.
A practical HTML and CSS hero implementation
If you are building a custom template, define the container ratio and let the image cover it while preserving a focal point.
<section class="hero" aria-labelledby="hero-title">
<img
class="hero__image"
src="/wp-content/uploads/hero.jpg"
alt="A team reviewing a product dashboard"
width="1600"
height="900"
fetchpriority="high"
>
<div class="hero__content">
<h1 id="hero-title">Build better reports</h1>
<p>Turn product data into decisions.</p>
</div>
</section>.hero {
aspect-ratio: 16 / 9;
min-height: 22rem;
position: relative;
overflow: hidden;
}
.hero__image {
width: 100%;
height: 100%;
object-fit: cover;
object-position: 50% 40%;
display: block;
}
.hero__content {
position: absolute;
inset: auto 2rem 2rem;
max-width: 36rem;
}
@media (max-width: fortyrem) {
.hero { aspect-ratio: 4 / 3; }
.hero__image { object-position: 60% 35%; }
.hero__content { inset: auto 1rem 1rem; }
}Replace fortyrem with a valid CSS value such as 40rem; it is written descriptively here to keep the example readable.
Registering a custom WordPress hero size
A custom theme can register a crop that matches its template. Add this to a theme or site-specific plugin, regenerate thumbnails after changing it, and use the registered name in the template.
<?php
add_action('after_setup_theme', function () {
add_image_size('article-hero', 1600, 900, true);
});
// In a template:
echo wp_get_attachment_image(
get_post_thumbnail_id(),
'article-hero',
false,
[
'loading' => 'eager',
'fetchpriority' => 'high',
]
);
The true argument requests a hard crop. Use it only when the template can tolerate cropping. If the subject must remain fully visible, use proportional resizing and control the layout separately.
Upload processing is different from display size
WordPress has a default big-image scaling threshold of 2560 pixels, documented in its media-processing guide. This threshold controls upload processing; it is not a recommendation that every hero should be 2560 pixels wide. The threshold can be changed when a site has a specific workflow.
Performance checklist
- Measure the actual largest rendered hero width before choosing an upload size.
- Use responsive image variants so narrow screens receive smaller files.
- Prefer WebP or another format supported by your WordPress setup when visual quality and browser support allow it.
- Compress the source while checking text, faces, gradients, and fine detail.
- Load the above-the-fold hero eagerly when it is the main content image; avoid lazy-loading every hero by default.
- Set width and height attributes to reduce layout shift.
- Do not ship a 4000-pixel original to a 600-pixel mobile layout unless the design genuinely requires it.
- Test Core Web Vitals and the Network panel on a throttled mobile connection.
Common errors and fixes
| Problem | Likely cause | Fix |
|---|---|---|
| Hero looks blurry | Selected variant is smaller than the rendered container | Register or select a larger size and regenerate thumbnails. |
| Subject is cut off | Cover or hard crop uses the wrong focal point | Adjust focal position, change object position, or use Contain. |
| Mobile downloads a huge file | Missing or incorrect srcset/sizes |
Use WordPress responsive markup and inspect the selected resource. |
| Image appears stretched | CSS width and height override the intrinsic ratio | Use height:auto for proportional images or intentional object-fit for fixed boxes. |
| New custom size is unavailable | Thumbnails were not regenerated after registration | Regenerate image derivatives, then clear page and CDN caches. |
| Text disappears on one breakpoint | Background crop removes the text area | Move text into HTML and reserve space with a focal point or breakpoint-specific crop. |
| Hero causes layout shift | No intrinsic dimensions or reserved aspect ratio | Set width and height attributes or use CSS aspect-ratio. |
Or skip the browser setup
If you need rendered screenshots for QA, documentation, or previews, ScreenshotNeo returns a PNG, JPEG, WebP, or PDF from one GET request. It removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets Claude, Cursor, and other MCP clients take screenshots, inspect pages, and capture PDFs.
See the ScreenshotNeo API documentation for all options.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://example.com/article \
-o hero.webpPython
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://example.com/article"},
timeout=90,
)
r.raise_for_status()
open("hero.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://example.com/article'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
await Bun.write('hero.webp', data);ScreenshotNeo supports full-page capture, CSS-selector element capture, device presets, custom viewports, retina scale, dark mode, custom CSS and JavaScript, waits, blocked resources, headers, cookies, user agents, geolocation, caching, signed links, asynchronous jobs, webhooks, bulk capture, and usage reporting. Responses include X-Page-Verdict and X-Billed headers so you can tell whether a clean page was billed.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots, and every feature is available on every plan. Create a free ScreenshotNeo account.
Reliability, performance, and cost notes
- Use a selector or network-idle wait when hero images load after JavaScript.
- Use a cache TTL for repeated previews and avoid recapturing unchanged pages.
- Capture only the hero element when a full-page image is unnecessary.
- Use asynchronous jobs and signed webhooks for slow pages or batch workflows.
- Bulk capture supports up to 100 URLs per call.
- Only clean shots are billed; inspect the verdict and billing headers in automated pipelines.
FAQ
Is 1920 × 1080 the correct WordPress hero size?
It can fit a 16:9 desktop hero, but it is not a WordPress standard. Confirm the theme’s container and mobile crop first.
Should a hero image be 2560 pixels wide?
No. 2560 pixels is the documented default big-image processing threshold, not a required display width.
Should I use JPG, PNG, or WebP?
Use the format that preserves the image’s important details at the smallest practical file size and is supported by your delivery setup.
Why does my featured image look different from the uploaded file?
The theme may select a registered sub-size or crop the image to fit its template. Inspect the rendered markup and theme image settings.
Can WordPress serve different hero sizes to phones and desktops?
Yes. WordPress can generate sub-sizes and responsive markup that lets the browser select an appropriate resource.
