WordPress Plugin Banner and Icon Sizes (2026)

I read the WordPress plugin handbook on 9 November 2026. I also checked how the 100 most popular plugins in the directory use their images.

This post covers each image size, the file names that make them work, and the mistakes that stop them showing.

WordPress.org doesn't use an upload form for plugin images. You commit them as files, and the file name tells the directory what each one is.

WordPress.org keeps these rules in three pages of the official plugin handbook.

1. 1The plugin assets page, which covers banners, icons and screenshots.
2. 2Its readme.txt page, which covers captions, tags and the short description.
3. 3The previews and blueprints page, which covers the Preview button.

All your images go in a folder called assets. It sits at the top level of your SVN repository, next to trunk and tags. Don't put it inside trunk, or inside a tag folder.

Here's the full set in one table. The size limits are the largest files the handbook allows.

The handbook adds the same note to every limit. Smaller files are better, because each image loads on every visit to your plugin page.

The banner is the wide image at the top of your plugin page. Its file must be named banner-772x250.png or banner-772x250.jpg.

The image must match the size in its name. A file called banner-772x250.png should be exactly 772 pixels wide and 250 pixels high.

You can add a second file, banner-1544x500, for high resolution screens. It's exactly twice the size of the normal banner. But it only works as an add-on. If you upload the large banner alone, the handbook says it won't be used.

There are no other banner sizes. The handbook warns that a renamed file in a new size simply won't show.

A banner is 772 pixels wide but only 250 high. That's a ratio of about 3 to 1, so there isn't much room for text.

Keep the design simple. A logo, a short line and a clear background usually work better than a crowded scene.

Think about other languages too. The handbook points out that the plugin directory runs in many languages, including Hebrew and Arabic. Those read right to left. Ideally, your banner's parts can sit in either direction and still look right.

Design at 1544 x 500 first, then scale down to 772 x 250. That way, both files match, and the small one stays sharp.

You can give the directory a different banner for other languages. The language goes on the end of the file name.

The 1544 x 500 banner takes the same endings. If a right to left language has no file of its own, the directory falls back to the rtl version.

Screenshots work in a similar way. A file named screenshot-1-de.png replaces screenshot-1.png when someone views your plugin in German.

Don't copy your English image under a new name without changing it. The handbook asks you not to, and the English file is used anyway. Our guide to right to left screenshots covers what to flip and what to keep.

The icon is the small square image beside your plugin's name. You've got three files to choose from.

PNG, JPG and GIF all work for the two square sizes. The handbook says there are no plans to change these sizes.

An SVG keeps the file small and stays sharp at every size. But you must still upload a PNG icon beside it. Without one, the handbook says your icon won't display properly in older browsers or on Facebook.

If you upload no icon at all, WordPress.org makes one for you automatically.

Your icon appears far more often than your banner. The handbook says it shows next to your plugin in search results on WordPress.org.

It also appears inside WordPress itself. When someone searches on the Add Plugins screen of their own site, each result shows the plugin's icon beside its name.

So the icon has to work small. Many users will see it at around the size of a thumbnail, in a list of similar plugins.

Use one bold shape or letter, with strong contrast. Fine detail and small text disappear at that size. Check it at 128 x 128 before you commit, since that's the smallest file you upload.

Screenshots have no required size. The handbook only limits the file to 10 MB, and it asks you to keep files smaller where you can.

Name them screenshot-1.png, screenshot-2.png and so on, in order. JPG works too. All file names must be lowercase, because uppercase names won't work.

The files must sit in your assets folder. The handbook says links to images hosted somewhere else won't display.

How many should you add? The handbook asks for one screenshot for every caption line in your readme. It doesn't set a maximum, but the top plugins give a useful guide, as you'll see below.

Our guide to PNG or JPG for screenshots explains which format keeps text sharper.

Captions don't go in the image. They come from a numbered list in the Screenshots section of your readme.txt file.

Each line in that list becomes the caption under the matching screenshot. The first line goes under screenshot-1, the second under screenshot-2, and so on.

The handbook's own example is a single line, "1. This is a monkey". That caption shows under the first screenshot.

So write each line as a short, plain label of what the screenshot shows. Name the screen and the result, like "The settings page with caching turned on." A caption that matches the picture helps people who skim.

Keep the numbers in step with your files. If you remove a screenshot, update the list too.

The assets folder can hold one more thing that changes how your page looks. That's a blueprint file, which turns on a Preview button.

The Preview button sits beside the Download button. It opens your plugin in WordPress Playground, a full WordPress site that runs inside the browser.

The button needs two things before it appears to everyone.

1. 1A valid blueprint.json file, placed at assets/blueprints/blueprint.json.
2. 2A committer must set the preview to public in the plugin's Advanced view.

Until then, only your plugin's committers see it, as a Test Preview button. The blueprint can set the page users land on and log them in, so they see your plugin working straight away.

The handbook gives the rules. I pulled the WordPress.org plugin data on 9 November 2026 to see what popular plugins actually do. The directory listed 74,393 plugins that day, and I looked at the 100 most popular.

The middle plugin had 6 screenshots, and the most was 18. So most top plugins add both banner sizes and around half a dozen screenshots.

Two text fields sit near your images, so they're worth getting right at the same time.

Your short description is the one line shown under your plugin's name. The readme handbook says to keep it to 150 characters or fewer, with no markup. Anything longer gets cut off.

Tags work like categories. You can use 1 to 5 of them, and the handbook says not to use competitors' plugin names as tags. Tags that only your plugin uses won't be shown either.

The top plugins treat both fields seriously. Among the 100 I checked, 93 used all 5 tags. Their median short description ran to about 136 characters, just under the limit.

If you make a WordPress theme, the rules aren't the same. Themes don't use banners or a numbered set of screenshots.

Instead, a theme ships one image file named screenshot. The theme handbook says it shows in the WordPress.org theme directory and in the admin dashboard.

That screenshot must not be bigger than 1200 x 900 pixels. That's a 4 to 3 shape, so design it to fill the frame.

Show your theme as it really looks, with a full page in view. A theme screenshot is often the only image people see before they install it.

Most image problems on WordPress.org come from a few small mistakes.

1. 1Images that download instead of opening. The handbook says this happens when SVN sends them with the wrong file type. Set the svn:mime-type property to image/png or image/jpeg.
2. 2A new image that doesn't show yet. Images go through a cache, so give it time. It usually takes a few minutes, but the handbook says 6 hours isn't unheard of at busy times.
3. 3A file name in capitals. Uppercase file names won't work, so rename them in lowercase.
4. 4The wrong size for the name. Each image must match the size in its file name exactly.
5. 5Images inside trunk. The assets folder belongs at the top level, not in trunk or a tag folder.

We make PlayMockUp, so weigh this part with that in mind. Our tool frames screenshots in phones and tablets for app stores. It doesn't make 772 x 250 banners.

That still fits some plugins. If your plugin changes what visitors see on a phone, such as a mobile menu or a booking form, a phone frame shows that clearly in one picture.

For screens of the WordPress admin, use plain screenshots at full width. A phone frame would only shrink the detail people want to read.

You can frame a mobile screenshot in our free mockup generator, then export it as PNG or JPG and add it to your assets folder.