Gallery for TYPO3

Why sf_filecollection_gallery solves image galleries in TYPO3 the right way

Image galleries are among the most common requirements on corporate websites - product photos, team pictures, event documentation, reference projects. TYPO3 itself does not include a native gallery element. The standard content element “Images” shows images stacked or in columns but without lightbox, without filtering and without flexible layout options. sf_filecollection_gallery fills this gap by using TYPO3 file collections as a data source for galleries, providing lightbox integration, various layouts and lazy loading.

The decisive advantage over other gallery extensions: editors work with the FAL system they already know. Images are organized in file collections, and the gallery automatically displays all images from the assigned collection. Adding new images means: drag image into the collection, done.

Typical use cases

Reference projects and portfolios. An architecture agency shows 15 to 40 images per project page in a gallery. The editor maintains one file collection per project. sf_filecollection_gallery renders the gallery as a grid with lightbox. Clicking an image opens the full view with navigation to the next and previous image. Image descriptions from FAL metadata (title, alt text, description) are automatically displayed as captions.

Event documentation and press photography. A trade show organizer documents each event with 50 to 200 photos. Images are batch-uploaded into a file collection. sf_filecollection_gallery automatically generates thumbnails, optimizes loading time through lazy loading and displays the gallery in masonry layout, which elegantly handles different aspect ratios.

Product catalogs with visual presentation. A furniture manufacturer shows an ambiance gallery per product category. Through multiple file collections (one per category) and a frontend plugin with category filter, visitors can switch between galleries without reloading the page.

Technical architecture

sf_filecollection_gallery is an Extbase extension that integrates as a TYPO3 plugin into content elements. The data source is TYPO3 file collections from the File Abstraction Layer (FAL).

The architecture is structured in three layers:

• Data source: the extension reads file collections through the TYPO3 FAL API. Supported are static collections (manually assigned files), folder-based collections (all files in a folder) and category-based collections.
• Rendering engine: Fluid templates control the output. The extension ships templates for grid layout, masonry layout and simple lists. All templates are overridable - through standard TYPO3 mechanisms (TypoScript template paths), custom Fluid templates can be integrated.
• Lightbox integration: sf_filecollection_gallery supports multiple lightbox libraries: Fancybox, PhotoSwipe and Lightcase. The choice is controlled via TypoScript configuration. Gosign recommends PhotoSwipe due to better touch support and no jQuery dependency.

Lazy loading is natively integrated: images below the visible area are only loaded when the user scrolls. This uses the native loading="lazy" attribute and optionally Intersection Observer for older browsers.

Dependencies: TYPO3 Core (v10+), FAL. Lightbox libraries are shipped as frontend assets or can be included through the project’s own asset pipeline. An advantage of the file collection architecture: images can appear in multiple galleries simultaneously without being duplicated. A reference to the same FAL object in different collections suffices. This saves storage space and ensures metadata (alt text, title, copyright) is centrally maintained.

Common problems and solutions

Gallery shows no images despite a filled file collection. Cause is frequently an incorrect storage configuration. The file collection references a storage the frontend cannot access (e.g. a non-public storage or a storage with an incorrect base URL). Solution: check in the TYPO3 backend under File List whether images reside in the correct storage and whether the storage is configured as “public”. Additionally, the plugin content element must have the correct starting point (SysFolder or page) configured where the file collection was created.

Lightbox does not work, images open as new page. The lightbox JavaScript library is not loaded. This is frequently caused by a missing TypoScript include or a conflict with another JavaScript library on the page. Solution: check in the browser dev tools whether the lightbox JS file is loaded and whether JavaScript errors appear in the console. With jQuery-based lightboxes (Fancybox), a jQuery version conflict may be the cause.

Loading time too high with large galleries. A gallery with 100+ images in high resolution can load slowly despite lazy loading because thumbnails are not sufficiently compressed. Solution: configure TYPO3 Image Processing to generate thumbnails at fixed dimensions (e.g. 400x300px) and optimized quality (75-80%). Additionally, enable WebP format through the TYPO3 image processing configuration.

Migration and version compatibility

sf_filecollection_gallery is actively maintained and available for TYPO3 v11 and v12 LTS. The extension has a stable API and minimal breaking changes between versions. For TYPO3 v13, compatibility is typically established shortly after the LTS release.

For those migrating from an older gallery extension (e.g. tt_products_gallery, ws_flexslider as a gallery substitute or custom gallery plugins), only the data source needs to change: organize images in file collections and place the sf_filecollection_gallery plugin on the pages. The images themselves remain in FAL and do not need to be moved.

During a TYPO3 upgrade from v10 to v12, the lightbox configuration should be reviewed. Fancybox 2 is no longer compatible with current jQuery versions. Gosign recommends switching to PhotoSwipe, which works without jQuery and delivers better performance on mobile devices. PhotoSwipe also supports touch gestures (pinch-to-zoom, swipe) that meet user expectations on smartphone screens. The migration from Fancybox to PhotoSwipe typically requires 4 to 8 hours: new JavaScript initialization, adapted lightbox template and CSS fine-tuning for transition animations.