Repository navigation
Gallery Slideshow Block
The Gallery Slideshow block (photopress/gallery-slideshow) shows the images of a Gallery block on the same page as a slideshow in the page. Clicking an image in the gallery shows that image in the slideshow.
- WordPress 6.6 or later.
- The block editor, and a core Gallery block in the same post or page.
- Block themes and classic themes both work. The block is rendered on the server.
- No jQuery or carousel library. The block's script has no dependencies.
- Add a Gallery block to the page and add its images.
- Insert the Gallery Slideshow block. It is in the Media category. Searching for "slideshow", "carousel" or "slider" finds it.
- In the block's placeholder, choose the gallery. You can also choose it later in Source › Gallery.
- To show visitors only the slideshow, turn on Hide the gallery.
The Source panel, with a gallery chosen.
In the editor the block shows the gallery's first image, its caption, a "1 of N" count and, with thumbnails on, the thumbnail row. The full slideshow runs on the page.
The editor preview, with thumbnails on.
A Gallery Slideshow block above its gallery.
| Control | What it does | Default |
|---|---|---|
| Gallery | The Gallery block on this page that the slideshow shows. Each is listed as "Gallery 1: 12 images (#anchor)". Choosing a gallery with no HTML anchor gives it one: gallery, or gallery-2, gallery-3 and so on if that is taken. |
Choose a gallery |
| Hide the gallery | Visitors see only the slideshow. The gallery stays in the editor, where you choose its images. | Off |
The slideshow finds its gallery by the gallery's HTML anchor. If no gallery on the page has that anchor, the panel shows: There is no gallery with the anchor "…" on this page.
The Slideshow panel.
| Control | What it does | Default |
|---|---|---|
| Transition | Slide or Fade. | Slide |
| Autoplay | Moves to the next image on a timer. See Autoplay. | Off |
| Seconds per image | 1–15. Shown while Autoplay is on. | 3 |
| Height offset (px) | 0–400. Images are never taller than the window minus this much, leaving room for the header. | 0 |
| Image size | The image size the slides use, from the sizes the editor offers. | Large |
| Show thumbnails | A row of the images under the slideshow. A click on one shows it. | Off |
| Thumbnail height (px) | 40–300. Shown while Show thumbnails is on. | 100 |
| Show captions | Each image's caption with its slide. | On |
| Caption position | Below, Left or Right. On phones, captions are always below the image. | Below |
| Caption padding (px) | 0–100. Space around the caption. | 0 |
| Caption max width (%) | 0–100, in steps of 5. A share of the slideshow's width. 0 or 100 means no limit. Captions stay at least about 50 characters wide (24em), or the full width where that is less. | 75 |
The three caption controls show while Show captions is on.
Caption max width on a desktop, and full-width captions on a phone.
Shown while Hide the gallery is off.
| Control | What it does | Default |
|---|---|---|
| Show clicked gallery images here | Clicking an image in the gallery shows it in this slideshow and scrolls to it, with an arrow to go back. | On |
| Scroll to the slideshow | Instantly or Smoothly. Shown while Show clicked gallery images here is on. | Instantly |
Align (wide, full), HTML anchor and Margin.
- The slides are built on the server each time the page is rendered, from the gallery's current images in gallery order. Images you add to or remove from the gallery appear in or leave the slideshow without editing the block.
- Each image appears once. Images with no attachment ID are left out.
- A gallery made before WordPress 5.9 is read from its
idsattribute. - A gallery whose images WordPress finds when it renders (
dynamicContent, WordPress 7.1) is read throughblock_core_gallery_resolve_dynamic_source(), when WordPress has that function. - With no gallery chosen, no gallery with the anchor, or no images, the block renders nothing.
- No slide, caption included, is taller than the visible window less Height offset and less the thumbnail row. On phones the visible height is the one with the browser's bars shown (
svh). - The slideshow is as tall as its tallest slide at its width, and keeps that height from slide to slide, so the page does not move. A shorter image sits in the middle.
- Each image is as large as fits, keeping its shape. A caption to the side takes its room from the image's width. A caption below takes it from the image's height.
The caption is the image's Media Library caption, from wp_get_attachment_caption(), filtered by wp_kses_post(). Left and Right captions sit beside the image, level with its bottom edge. In a window 600 px wide or less they go below the image.
| Input | Action |
|---|---|
| Mouse press on the left or right half | Previous or next image. A large chevron at the pointer shows the direction. |
| Swipe left or right (touch) | Next or previous image. The swipe must be more than 40 px and more horizontal than vertical. |
| Tap on the left or right half (touch) | Previous or next image. The chevron shows for a moment where the tap landed. |
| Left and Right arrow keys | Previous and next image, while the slideshow or a control in it has the focus. |
| Tab | Reaches the slideshow, Previous image, Next image, the return button and the thumbnails. |
| Click on a thumbnail | Shows that image. |
The mouse navigates on the press, not on release. Links, the return button and the thumbnails keep their own behavior. Going from the last image to the first, or back, is instant. For visitors who ask for reduced motion, every change is instant.
Presses on the right and left halves move the slideshow.
Show thumbnails on. The current thumbnail is brought to the middle of the row.
With Show clicked gallery images here on:
- A click on a gallery image shows that image in the slideshow at once.
- The page scrolls the slideshow to the top of the window, instantly or smoothly as Scroll to the slideshow sets.
- A round return button appears in the slideshow's top right corner. It scrolls smoothly back to the image that was clicked, and stays visible after use.
A click with a modifier key (Ctrl, ⌘, Shift, Alt) is left to the gallery: it opens the image's link as usual, or the full-screen slideshow if the gallery has Slideshow on. The block handles the click before the image's link and before the Full-Screen Slideshow, so a gallery that also has Slideshow on does not open the full-screen slideshow on a plain click.
The gallery is hidden in the page's markup, with the hidden attribute and the photopress-hidden-gallery class (display: none), so it never shows while the page loads. The gallery and slideshow blocks can be in either order.
- Autoplay starts when the page loads.
- It stops while the browser tab is hidden and starts again when it is shown.
- It pauses while a mouse pointer is over the slideshow, and starts again when the pointer leaves. A touch does not pause it.
- It pauses while a keyboard user has the focus in the slideshow, and starts again when the focus leaves.
- It keeps going after a click or a swipe.
- It is off for visitors who ask for reduced motion.
- The shortest interval is 1 second.
- The first slide's image loads with the page (
loading="eager"). - Every other slide starts with a 1×1 placeholder. Its
srcandsrcsetare kept indata-srcanddata-srcset, and the script loads them for the current slide and the slides on either side. - Each image carries its shape as an inline
aspect-ratio, so slides keep their size before their images load. - Thumbnails load lazily (
loading="lazy"). - Without JavaScript, the first slide shows and the others do not.
WordPress gives each slide image the default sizes of the chosen image size. The script replaces it with the width the image is shown at, in pixels: the slide's width less a side caption, or the slide's allowed height less a caption below, times the image's shape, and no wider than the image's width attribute. It updates sizes when the slideshow changes size, so the browser loads a larger file from srcset when the image grows. Thumbnails get sizes of their own width.
- The block is a region (
role="region"), described as a "slideshow" and labeled "Slideshow". It can take the focus (tabindex="0"). - Each slide is a group described as a "slide". Slides not showing are
aria-hidden. - The halves are buttons named Previous image and Next image. The return button is named Return to gallery image.
- Each change of image is announced in a polite live region as "3 / 12".
- Each thumbnail is a button named by its image's alt text, or by its place ("3 / 12"). The current one has
aria-current="true".
| Hook | Type | Code | Purpose |
|---|---|---|---|
render_block_core/gallery |
filter | GallerySlideshow.php#L166 | Hides a gallery that a Gallery Slideshow block in the same post shows with Hide the gallery on. |
Registration:
-
register_block_type()from block.json, withGallerySlideshow::render()as itsrender_callback(gallery.php#L52). The block saves only its attributes. Itssavereturnsnull. - On WordPress 6.7 and later,
wp_register_block_metadata_collection()registers the built manifest indist/blocks-manifest/, so block.json is not read on each request (class-util.php#L50). -
viewScriptisphotopress-gallery-slideshow(dist/gallery-slideshow.build.js), so the script loads only on pages where the block renders. It is registered withwp_register_script()in the footer withdefer(gallery.php#L42). The Full-Screen Slideshow uses the same script. -
styleisphotopress-frontend(dist/blocks.style.build.css). -
usesContext:postId. The block reads the gallery from that post, or fromget_the_ID().
Core functions relied on:
-
parse_blocks()andget_post()to find the gallery by its anchor, at any depth (findGallery). The anchor is read from the block'sanchorattribute, or else from theidof the gallery's saved markup (anchorOf). -
has_block()to check for the block before looking for galleries to hide (hiddenGalleries). -
wp_get_attachment_image()for each slide's image, andWP_HTML_Tag_Processorto defer it (prepareImage). -
wp_get_attachment_caption()andwp_kses_post()for captions. -
get_block_wrapper_attributes()for the wrapper, its classes,data-*attributes and CSS variables. -
block_core_gallery_resolve_dynamic_source(), when it exists, for a dynamic gallery (imageIds).
Scripts and styles:
| Source | Does |
|---|---|
| src/frontend/gallery-slideshow.js | Starts a slideshow on each .wp-block-photopress-gallery-slideshow, and the full-screen slideshow if the page has one. |
| src/shared/slideshow.js | Slides, loading, sizes, thumbnails, arrow keys, autoplay (L338), gallery navigation (L383). |
| src/shared/press-navigation.js | Press, swipe and tap navigation, and the chevron. |
| src/blocks/gallery-slideshow/edit.js | The editor preview and the sidebar. |
| src/blocks/gallery-slideshow/style.scss | Styles, shared with the full-screen slideshow. |
Block attributes, in the block comment (block.json#L10):
| Attribute | Type | Default | Control |
|---|---|---|---|
galleryAnchor |
string | "" |
Gallery |
hideGallery |
boolean | false |
Hide the gallery |
effect |
slide, fade
|
slide |
Transition |
autoplay |
boolean | false |
Autoplay |
delay |
number | 3 |
Seconds per image |
maxHeightOffset |
number | 0 |
Height offset (px) |
sizeSlug |
string | large |
Image size |
showThumbnails |
boolean | false |
Show thumbnails |
thumbnailHeight |
number | 100 |
Thumbnail height (px). Clamped to 40–300 on render. |
showCaptions |
boolean | true |
Show captions |
captionPosition |
below, left, right
|
below |
Caption position |
captionPadding |
number | 0 |
Caption padding (px) |
captionMaxWidth |
number | 75 |
Caption max width (%) |
galleryNavigation |
boolean | true |
Show clicked gallery images here |
scrollBehavior |
instant, smooth
|
instant |
Scroll to the slideshow |
Choosing a gallery with no anchor also sets that gallery's anchor attribute.
A Jetpack Slideshow block (jetpack/slideshow) set up by the "Slideshow Source: Gallery" plugin can be converted with Transform › Gallery Slideshow (transforms.js#L16). The transform uses the block editor's transforms API.
| Jetpack Slideshow attribute | Gallery Slideshow attribute |
|---|---|
paaSourceGalleryAnchor |
galleryAnchor |
sizeSlug |
sizeSlug (large if unset) |
autoplay |
autoplay |
delay |
delay (3 if unset) |
effect |
effect (fade, else slide) |
paaMaxHeightOffsetPx |
maxHeightOffset |
paaGalleryNavEnabled |
galleryNavigation (on unless false) |
paaScrollBehavior |
scrollBehavior (smooth, else instant) |
align |
align |
The transform is offered only for a Jetpack Slideshow that has paaSourceGalleryAnchor. That attribute exists only while "Slideshow Source: Gallery" is active, so convert the blocks before you deactivate it. Without Jetpack, no transform is offered.
| Name | Kind | Details | Code |
|---|---|---|---|
photopress-slideshow-change |
DOM event | Dispatched on the block's root element when the current image changes, and once when the slideshow starts. event.detail.index is the image's position, from 0. Does not bubble. |
slideshow.js#L286 |
element.photopressSlideshow |
JavaScript property | Set on each block's root element once its slideshow starts: show( index ), next(), prev(), current(), destroy(). |
gallery-slideshow.js#L16 |
- The gallery must be in the post's own content, at any depth (inside a Group or Columns block, for example). A gallery in a template, a template part or a synced pattern is not found.
- If two galleries have the same anchor, the first one is used.
- Changing the gallery's HTML anchor after choosing it breaks the link. The Source panel then shows the warning, and the page shows nothing.
- The caption is always the Media Library caption. A different caption typed into the gallery is not shown.
- The Gallery link panel is hidden while Hide the gallery is on. Its saved values are kept.