A gallery is a performance problem wearing a layout problem's clothes. The layout question - grid, masonry, arc, bento - takes an afternoon. The part that decides whether the page is usable is how many bytes arrive before the first row is readable, and almost every gallery component in every catalogue leaves that entirely to you.
57 public components on 21st have "gallery" in the name. They sort into four layouts and one interaction, and then into the part that matters.
The grid
Equal cells, fixed aspect ratio, one object-cover. It is the layout that never looks broken, and it is what most projects should ship.
Gallery by Ali Imam and Image Gallery by prebuiltui are the plain versions. Gallery with image cards from Shadcnblocks.com is the editorial take, full-height image cards carrying case-study text.
The grid's one weakness is portrait and landscape mixed together: cropping to a square loses the subject of half the images. If the set is genuinely mixed and the crop matters, that is the argument for masonry, and the only good one.
Masonry
Variable heights, packed columns, no cropping. Worth knowing that CSS now does most of this natively: column-count has always worked but reads top-to-bottom per column, and CSS grid with masonry layout is arriving but not yet safe to rely on across browsers. A small JavaScript packer is still the pragmatic choice when reading order matters.
Only 4 public components here have "masonry" in the name, which tells you how rarely it is the right answer.
Bento
Cells of deliberately different sizes on a fixed grid, with the important image given more room. Interactive Bento Gallery by Anurag Mishra is the version with movement built in.
Bento works when the set is curated and small, six to twelve items, and someone has decided which one is the hero. It fails on a feed, because the layout implies a ranking that arbitrary content does not have.
The showpieces
When the gallery is the hero rather than an index. 3D Gallery Photography and 3D Image gallery by shadway put the images in perspective. Circular Gallery by Ravi Katiyar rotates them through a ring, Arc Gallery Hero Component by Le Thanh fans them across the top of a page, and Hero Gallery Scroll Animation by youcefbnm ties the arrangement to the scroll position.
Gallery Hover Carousel by Ruixen UI and Animated Gallery by youcefbnm sit between the two families: a real index, with movement.
These are for a portfolio, a case study or a launch page. They are the wrong shape for an archive of four hundred images, where the reader wants to find one thing.
The lightbox
Opening an image full size is the one interaction a gallery needs, and it is a dialog: focus moves into it, Tab stays inside, Escape closes, focus returns to the thumbnail that opened it. Arrow keys move between images and the position is announced.
The decision worth making early is whether the open image has a URL. If it does, the image is linkable, shareable and reachable by a crawler, and the back button does what everyone expects. If it does not, none of that is true. For a portfolio it rarely matters; for a product catalogue it matters a lot.
The part that decides whether it is fast
Four rules, and they are worth more than any layout choice above.
Serve the size you display. A srcset with a sizes attribute lets the browser pick a 400px file for a 400px cell instead of downloading the 2400px original. This single change is usually the difference between a gallery that loads and one that does not.
Lazy-load everything below the fold, and only that. loading="lazy" on offscreen images, and explicitly loading="eager" with fetchpriority="high" on the first row, because a lazy hero image is a slower Largest Contentful Paint, not a faster one.
Reserve the space. Every image needs width and height attributes, or an aspect-ratio on its container. Without them the page reflows as each file lands, which is the second half of the Cumulative Layout Shift problem.
Do not decode four hundred images. Past a screen or two, paginate or virtualise. Decoding is CPU work that happens off the main thread but still competes for it, and a phone will run out of memory before it runs out of patience.
One more, easy to forget: every image needs alt text that describes it, or an empty alt="" if it is genuinely decorative. A gallery of forty images with forty filenames as alt text is worse than no alt text at all.
Where else to look
The honest list of alternatives, because the answer is not always us:
| Source | Best for | Trade-off |
|---|---|---|
| next/image | Sizing, formats, lazy loading and layout stability, handled | Next.js only, and the optimiser has a cost model to understand |
| PhotoSwipe / yet-another-react-lightbox | The lightbox: gestures, zoom, keyboard, focus trapping | A dependency for one interaction |
CSS grid and column-count | Grid and column layouts with no JavaScript at all | No packing algorithm, no reading order control |
| 21st | The showpieces: arcs, rings, bento, scroll-driven galleries | Quality varies by author, so preview before you take it |
Taking one
Every component page has a live preview and the code. Installing goes through the shadcn CLI against our registry:
That key comes from your 21st account, and installs require a membership. Set API_KEY_21ST once in your shell and the command works for anything in the catalogue. The 21st MCP covers the same ground without leaving the editor: ask Claude, Cursor or Codex for a gallery, get the previews inline, and let the agent write the file.
Frequently asked
- Grid or masonry for an image gallery?
- Grid unless the images are genuinely mixed portrait and landscape and cropping loses the subject. An equal-cell grid with a fixed aspect ratio and object-cover never looks broken and needs no packing logic. Masonry earns its place only when the crop itself is the problem, which is rarer than the layout's popularity suggests.
- How do you make an image gallery fast?
- Four rules. Serve the size you display with srcset and sizes rather than the full-resolution original. Lazy-load below the fold but load the first row eagerly with fetchpriority high. Reserve space with width and height or aspect-ratio so nothing reflows. And past a screen or two, paginate or virtualise instead of decoding hundreds of images.
- Should a lightbox change the URL?
- If the image deserves to be shared, linked or found, yes. A lightbox without a URL means no back button, no sharing, and nothing for a crawler to reach. For a portfolio it rarely matters; for a product catalogue it matters a lot. Either way it is a dialog: trap focus, close on Escape, and return focus to the thumbnail.
- What alt text does a gallery need?
- A description of what is in the picture, or an explicitly empty alt attribute when the image is purely decorative. Filenames as alt text are worse than nothing, because a screen reader then reads forty strings of characters instead of skipping forty decorative images.