How to show all images attached to a post in a WordPress gallery

Some of my older themes, like Koji, use the images attached to a post to show a carousel. It’s a handy feature, but it’s always been a difficult one to explain, and one of my most common sources of support requests. An image is attached to a post if you upload it while you’re editing the post. Back in the days of classic themes, before the block editor, you could fetch all of the images attached to a post and display them outside of the post content (in a carousel, for example) without having to register custom fields, which is prohibited for themes in the WordPress.org theme directory. It was a bit of a hack, in other words.

You could also display attached images with the old

shortcode. If you added one to the post content without selecting specific images, the gallery would show every image attached to the post, and keep itself up to date as you added more.

The Gallery block never had an equivalent, which has made it a feature gap between classic themes and block themes, and a source of frustration for people who have old posts with empty

shortcodes, which are left as Shortcode blocks when the posts are converted to blocks. Every image had to be picked by hand, and every new one had to be added to the gallery manually. With WordPress 7.2, that’s finally changing: the Gallery block can now show all the images attached to a post, and update automatically when you add new ones.

In this tutorial, we’ll take a look at how to set it up, and why some of your images might not show up in it.

  1. Add a Gallery block to your post or page.
  2. With the block selected, open the “Settings” tab in the block sidebar. Under “Source”, click “Use attached images”.
  3. If the gallery already has images in it, WordPress asks you to confirm that you want to replace them. The images aren’t deleted: they stay in the Media Library.

The block turns into a “Dynamic Gallery”, which shows every image attached to the post, newest first. If you upload images to the post later, they show up in the gallery automatically, without you having to touch it.

The “Order by” setting lets you change the order to oldest first, by title from A to Z or Z to A, or random. Random shuffles the images every time the page loads.

The other gallery settings work just like before: columns, cropping, links to the images and so on. What you can’t do is reorder or remove individual images, since the gallery picks its own images. If you want to do that, click “Detach” in the block toolbar, or “Detach Gallery” under “Source”. The gallery keeps the images it has, turns into a regular gallery that you can edit, and stops updating automatically.

Why some images are missing

“Why isn’t my image showing up?” is the question I’ve gotten most often about the carousel in Koji, and it’s likely to come up with the Gallery block too. If you set up the gallery on an existing post, there’s a good chance some of the images you expected are missing. That’s because “attached” has a specific meaning in WordPress, and it’s not the same as “used in the post”.

As I mentioned above, an image only counts as attached if it was uploaded while you were editing the post. If you pick an image that’s already in the Media Library, it stays attached to wherever it was uploaded first, or to nothing at all if it was uploaded directly to the Media Library. And an image can only be attached to one post at a time.

So a post can be full of images, and still have none of them attached to it. You can see where each image is attached in the Media Library:

  1. Go to “Media” → “Library”, and switch to the list view with the icon next to the filters.
  2. The “Uploaded to” column shows which post each image is attached to. Images that aren’t attached to anything have an “Attach” link instead.
  3. Click “Attach”, search for your post, and select it. The image shows up in the gallery right away.

To move an image that’s attached to another post, click “Detach” first, and then “Attach”. Keep in mind that if the image is in a gallery like this on the other post too, it’ll disappear from that one.

Things to keep in mind

  • Every attached image is included. That includes the featured image, if you uploaded it to the post, and images you uploaded for other blocks in the post. If one of them doesn’t belong in the gallery, detach it in the Media Library, or detach the gallery and remove it there.
  • The gallery shows up to 100 images. If more than that are attached, the editor shows a notice, and the rest are left out.
  • Only images are shown. Videos, PDFs and other files attached to the post are skipped.

WordPress 7.2 is still in development, and some of the finer details above might change before the planned release in early December. I’ll update the tutorial once it’s out.