PhotoSwipe for TYPO3

On mobile devices, image galleries only work with touch-optimized lightboxes

Most TYPO3 websites use lightboxes that were built for desktop browsers: Fancybox, Colorbox, Magnific Popup. On smartphones and tablets these solutions feel foreign, because zoom and navigation respond to mouse clicks rather than touch gestures. PhotoSwipe is a JavaScript library built for touch from the ground up. The TYPO3 extension integrates PhotoSwipe as an image gallery with pinch-to-zoom, swipe navigation and a responsive layout. At under 30 KB (minified + gzip), PhotoSwipe is also one of the most lightweight lightbox solutions on the market.

For websites with a high share of mobile traffic, which today means practically all of them, this is not an optional improvement but a functional requirement. Visitors expect the same gestures they know from the native photo app on their smartphone.

Typical use cases include portfolio galleries, product images and media archives

The most common scenario is the portfolio gallery on agency, architecture or photography websites. A photographer shows 20 to 40 images per project. Visitors click a thumbnail, see the image in full resolution, pinch to zoom and swipe to the next image. Deep linking means every image has its own address that can be shared or linked to; since PhotoSwipe v5 you have to build it yourself, because the built-in hash module was dropped. For SEO these addresses do not count, since Google does not treat fragments after the # sign as separate URLs; what counts for image search are <img> elements with meaningful alt text and descriptive file names.

A second scenario is product detail pages in TYPO3 installations with an e-commerce focus. A furniture manufacturer shows five views of each product. PhotoSwipe renders them as a gallery with high-resolution zoom, activated by mouse wheel on desktop and by double tap on touch devices. Zoom quality depends directly on the resolution of the source image, so we recommend a width of at least 2,000 pixels for product images meant to be viewed up close.

The third scenario is media archives and press areas. A university provides 500 event photos. PhotoSwipe renders the gallery efficiently, because images only load as users page through them (lazy loading). The thumbnail overview shows 50 images per page without noticeable load time.

The technical architecture hooks PhotoSwipe into TYPO3’s image enlargement

The extension does not bring its own content element; instead, it enables PhotoSwipe for TYPO3’s native image enlargement. Editors add images from the FAL media library to the usual image content elements, enable “Enlarge on Click” and add optional captions. During rendering, the extension attaches the width and height of each image to the link as data attributes; the PhotoSwipe JavaScript library builds the gallery from them.

PhotoSwipe itself has no dependencies: no jQuery, no framework. The library consists of one CSS file and one JS file. The TYPO3 extension registers both through the AssetCollector’s PHP API in its ext_localconf.php, so they are included on every page, whether or not it contains a gallery. To avoid unnecessary requests, include the files with the Fluid ViewHelpers f:asset.css and f:asset.script in the gallery template instead; then they only end up on pages with a gallery.

For responsive images, the extension supports srcset attributes, so the browser loads the right image size for each viewport. TYPO3 image processing generates the variants automatically. Combined with WebP conversion (see the webp extension), PhotoSwipe galleries achieve optimal load times.

Common problems involve conflicts with other lightbox extensions and missing image dimensions

The most frequent problem is a conflict with a lightbox extension that is already installed. If Fancybox and PhotoSwipe are active at the same time, both respond to image clicks and create double overlays. The fix: deactivate the old lightbox extension and remove its CSS/JS includes from the TypoScript setup. A grep for “fancybox” or “colorbox” in the TypoScript files shows whether remnants of the old library are still being loaded.

The second problem is missing image dimensions. For zooming, PhotoSwipe needs the actual pixel dimensions of the image. If the extension cannot read them from the FAL metadata, zoom does not work or jumps to the wrong size. The fix: check the FAL metadata of all gallery images. TYPO3 reads width and height automatically on upload, but images that were imported or added via the CLI sometimes have empty metadata.

PhotoSwipe v5 runs on TYPO3 v12 and v13 without a template update

The current PhotoSwipe library is at version 5. The TYPO3 extension has been adapted to various TYPO3 versions and runs stably on v12. For TYPO3 v13, no template update is needed, because version 2.0.10 of the extension supports v12.4 and v13 alike. During TYPO3 upgrades, Gosign updates all frontend extensions, lightboxes included, and checks that the touch gestures work correctly on current iOS and Android versions.