CMS Gallery Kit · Documentation · Version 1.1
Your CMS galleries, finally in a carousel.
How to connect a CMS gallery field, the five layouts, navigation and lightbox, every setting in the panel, and four looks to start from.
01
Start here.
Add it to your project. Open the link in your purchase email (or the Marketplace page) and drop CMS Gallery Kit on a page. It arrives with six demo photos so you can see it work.
Feed it photos. On a CMS detail page (a room, a project, a case study) or inside the items of a Collection List, connect Slides to your Gallery field. Anywhere else, add images by hand in Slides. The next section shows the CMS steps.
Pick a layout. Carousel, Slideshow, Thumbnails, Grid or Masonry. Set the height to Fit so Aspect ratio decides the shape.
Make it yours. Set arrows, indicator, radius, gap, captions and colours to match the site. Then preview and click a photo to try the lightbox.
02
How it works.
The component reads a list of images and shows them in the layout you pick. Each slide has an image, an optional caption and an optional alt text.
Bind Slides to a CMS Gallery field and every item in the gallery becomes a slide, in the same order.
No API keys, no backend, no tracking. The component makes no network requests of its own. Only your images load.
Images load from Framer’s own srcSet, so phones get small files and large screens get sharp ones.
Only the first photo loads right away. The rest load as they come close to the screen.
Live component with demo photos. On a CMS page its Slides come from your Gallery field.
03
Connect a CMS gallery field, step by step.
Framer has no built-in way to turn a CMS Gallery field into a slideshow. This component does it.
Open the CMS detail page of your collection, for example /rooms/:slug, or the page with your Collection List.
Select CMS Gallery Kit on that page. In a Collection List, it goes inside the list item.
In the property panel, find Slides and click the small connect button (the + or the dot) next to it.
Choose your Gallery field from the list.
Map Image → image. Framer asks which part of each gallery item goes where: the gallery image goes to Image.
Preview a few CMS items. Each one shows its own photos.
Inside a Collection List. A page that lists many items, like a one-page portfolio, works the same way: put CMS Gallery Kit inside the list item and connect Slides there. Every item gets its own gallery with its own photos, and with Autoplay on, each one moves on its own. All the galleries in the list share the same settings. Autoplay pauses for the ones that are off screen, and each gallery only loads the photos it needs, so a long list stays light.
Good to know:
The alt text you write in the CMS for each image is read by screen readers. Fill it in.
A gallery field has no captions. To show captions, add images by hand instead, or use Overlay or Hidden captions with CMS photos.
An item with an empty gallery shows nothing on the published site. On the canvas you see grey placeholder slides, so the layout stays easy to design.
The demo photos disappear as soon as Slides is connected or edited.
04
Layouts
A row of slides that scrolls sideways and snaps into place. Swipe on touch, drag with the mouse on desktop. Per view sets how many slides fit: Auto fits as many as Min width allows and stretches them to fill the row, or fix it at 1, 2 or 3.
One photo at a time. Transition is Fade (a crossfade) or Slide. Speed sets how long it takes.
A large photo with a row of small ones underneath. Click a thumbnail to show it. Thumb height sets their size.
Every photo at once, in Columns. Click any photo to browse in the lightbox.
Two styles. Bento mixes large, tall and wide tiles in a repeating pattern and always closes the last row, like a bento box; captions show only as Overlay. Columns lets each column flow down on its own, and with Aspect ratio Original every photo keeps its shape.
Height. Set the component’s height to Fit and Aspect ratio sets the shape. Give Carousel, Slideshow or Thumbnails a fixed or Fill height and the photos fill it instead, for example a full-screen hero.
Different layout per breakpoint. Each breakpoint keeps its own settings. A common setup: Grid with 3 columns on Desktop, Carousel with Per view 1 on Phone.
06
Lightbox
Turn on Lightbox and a click on any photo opens it full screen.
Arrows, a counter, the caption and a close button.
Escape closes it. The left and right arrow keys move between photos. On touch screens, swipe.
Focus stays inside while it’s open and goes back to the photo you clicked when it closes.
The page behind it doesn’t scroll.
It opens on top of everything, so no section or overflow setting can clip it.
The next and previous photos load in the background, so browsing feels instant.
Set Lightbox fill and Lightbox text to match the site. It always loops.
07
Customize the look.
Image
Aspect ratio: Original, 1:1, 4:3, 3:2, 16:9 or 4:5. Original keeps each photo’s shape in Masonry Columns; in Bento, Aspect ratio sets the height of a single tile. Other layouts take the shape of the first photo, so slides line up.
Fit: Cover fills the frame and crops the edges. Contain shows the whole photo, with Image fill around it.
Radius, Gap and Image fill (also shown while photos load).
Hover zoom: a slow, slight zoom on photos you can click.
The focal point you set on an image in Framer is respected with Cover.
Captions
Below: text under each photo. In Slideshow and Thumbnails, the current photo’s caption.
Overlay: text over the bottom of the photo, on a soft dark gradient. Set Overlay text.
Hidden: no captions on the page. The lightbox still shows them.
Set Caption font and Caption colour.
Colours
Accent colours the active dot, the counter, the progress bar, the active thumbnail and the keyboard focus ring. Track colours the inactive dots and the progress bar’s track. Pick your site’s colour styles in each one so the gallery follows your palette.
Recipes
Layout Slideshow · Transition Fade · Aspect 3:2 · Radius 0 · Captions Overlay · Arrow position Sides · Arrow style Circle · Indicator Counter · Lightbox on
Layout Carousel · Per view Auto · Min width 420 · Aspect 4:5 · Radius 0 · Gap 4 · Arrow position Bottom right · Arrow style Minimal · Indicator Progress bar · Captions Below
Layout Thumbnails · Aspect 1:1 · Fit Contain · Image fill #F5F5F5 · Radius 16 · Thumb height 64 · Arrows off · Indicator None · Hover zoom on
Layout Masonry · Masonry Columns · Aspect Original · Columns 3 (2 on Tablet, 1 on Phone) · Gap 24 · Radius 0 · Captions Below · Lightbox fill your darkest colour
08
Settings reference.
In the order they appear in the property panel. Settings that don’t apply to the current layout are hidden.
Content
Slides — the photos. Each one has Image, Caption and Alt text. Connect it to a CMS Gallery field or add items by hand. Up to 60.
Layout
Carousel, Slideshow, Thumbnails, Grid or Masonry.
Carousel: Auto, 1, 2 or 3.
Carousel with Auto: the narrowest a slide can be.
Slideshow and Thumbnails: Fade or Slide.
Slideshow and Thumbnails: transition length in milliseconds.
Grid and Masonry: 1 to 6.
Bento or Columns.
Thumbnails: the height of each thumbnail.
Behaviour
Drag or swipe with the mouse on desktop.
Start again after the last slide.
Move on by itself.
Seconds between slides with Autoplay.
A pause and play button next to the indicator.
Navigation
Arrows — show or hide them.
Arrow position — Sides, Bottom right or Outside.
Arrow style — Circle, Square or Minimal.
Arrow size, Arrow icon, Arrow fill.
Indicator — None, Dots, Counter 03 / 12 or Progress bar.
Accent — active dot, counter, progress, active thumbnail and focus ring.
Track — inactive dots and progress track.
Counter font — the counter under the gallery and in the lightbox.
Image
Aspect ratio — Original, 1:1, 4:3, 3:2, 16:9 or 4:5.
Fit — Cover or Contain.
Radius, Gap.
Image fill — behind photos while they load and around them with Contain.
Hover zoom — with Lightbox on.
Captions
Captions — Below, Overlay or Hidden.
Caption font, Caption (colour), Overlay text.
Lightbox
Lightbox — open photos full screen on click.
Lightbox fill, Lightbox text.
Text
Gallery label — what screen readers call the gallery. Name it after the page, like Room photos.
Previous label, Next label — the arrow buttons.
“of” word — screen readers hear 3 of 12. Translate it with the rest.
Open label, Close label, Viewer label — the lightbox.
Pause label, Play label — the pause button.
All of them are translated by Framer Localization.
09
Performance
No network requests of its own, no scripts from other sites, no tracking.
Every image uses Framer’s srcSet with a sizes value worked out from the real width of each slide, so the browser downloads the right file.
The first photo loads right away. Every other photo is lazy loaded.
Slideshow and Thumbnails only load the current photo and its neighbours, then keep them.
The carousel uses the browser’s own scroll and snap, so it stays smooth on phones.
Autoplay stops when the gallery is off screen.
On the canvas and in Framer’s static previews, it renders still: no autoplay, no motion.
10
Accessibility
Carousel, Slideshow and Thumbnails are announced as a carousel. Each slide is announced as “3 of 12”.
Arrows, dots, thumbnails and the pause button are real buttons with labels you can translate.
Alt text comes from the Alt text field, or from the image’s own alt text in Framer or the CMS.
Works with the keyboard: Tab to reach the gallery, arrow keys to move, Enter to open the lightbox.
The lightbox traps focus, closes with Escape and gives focus back.
Autoplay pauses on keyboard focus and has a pause button. It starts paused for visitors who prefer reduced motion, and every transition is instant for them.
Screen readers hear the new position after each move, except while autoplay runs, so they aren’t interrupted.
11
Troubleshooting
The component isn’t on a CMS detail page or inside a Collection List item, or the collection has no Gallery field. Add one in the CMS, then try again.
Image isn’t mapped. Connect Slides again and map the gallery’s image to Image.
The component has a fixed or Fill height. Set its height to Fit.
Fit is Cover. Switch to Contain, or pick an aspect ratio closer to your photos.
Slides isn’t connected yet. Connect it or replace the items.
Gallery fields have no captions. Use images added by hand to write them.
Use Arrow style Circle with a light Arrow fill, or move them Outside.
The mouse is over the gallery, it has keyboard focus, or your device asks for reduced motion. Press play.
There are more than 12 positions. Pick Progress bar or Counter if you prefer.
That CMS item’s gallery is empty.
12
Updates
New versions are free and listed here. To update, insert the component again from the Marketplace page or from the link in your Polar order, which always points to the latest version, and copy your settings across.
— Masonry Bento: large, tall and wide tiles that fit together and always close the last row, with captions only as Overlay. The previous Masonry stays as Masonry Columns.
— First release: Carousel, Slideshow, Thumbnails, Grid and Masonry, CMS Gallery binding, lightbox, autoplay with pause, arrows in three styles and three positions, dots, counter and progress bar, captions below or overlay, and full documentation.
13
Support and licence.
Questions or a bug? Write to info@miguelrecio.es. A person replies within two business days (Mon–Fri, CET).
One licence covers one designer and unlimited client projects. Reselling or redistributing the component isn’t allowed.
Demo photos are from Unsplash. Replace them with your own before you publish.