pxe_compareslider

Extension key: pxe_compareslider
Package name: pixelegg/pxe-compareslider
Version: 2.2.0
Language: en
Author: pixelegg
License: GPL-2.0-or-later

Before/after image comparison slider content element for TYPO3 13.4 LTS and 14.

Two images are stacked on top of each other. Visitors drag a handle to reveal more of the "before" or the "after" image, horizontally or vertically. The script is dependency-free vanilla JavaScript; the handle is keyboard and touch accessible; images are responsive.

Horizontal compare slider with the handle in the middle: muted landscape on the left, vivid version on the right — Horizontal slider on a demo page with a minimal theme, handle at the start position 50 %.

Requirements

TYPO3 13.4 LTS or 14, PHP 8.2–8.4
EXT:fluid_styled_content (rendering uses lib.contentElement)

Installation

composer require pixelegg/pxe-compareslider

Non-composer installations: install pxe_compareslider from the TER.

Then load the TypoScript in one of two ways:

Site Set: For sites configured entirely through sets (no root sys_template record): edit your site (TYPO3 13.4: Site Management → Sites, TYPO3 14: Sites → Setup) and add the set Compare slider (before/after) (pixelegg/compareslider), or list it in the dependencies of your own set. The set depends on typo3/fluid-styled-content. Settings are editable in the site's Settings editor.
Static template: For sites with a root sys_template record: module TypoScript (TYPO3 13.4: under Site Management, TYPO3 14: under Sites) → edit the root TypoScript record → tab Advanced Options → Include TypoScript sets: add Compare slider (before/after) after Fluid Styled Content. Settings are TypoScript constants.

Both load the same setup. TYPO3 13/14 ignore set TypoScript as soon as the root page has a sys_template record, so on such sites only the static template takes effect. No database changes are required.

Usage

Add a content element and choose Compare slider (before/after) from the tab Typical page content of the new content element wizard (same name in TYPO3 13.4 and 14).

New content element wizard with Compare slider (before/after) in the first tab — The element in the new content element wizard (TYPO3 14, tab "Typical page content").

General tab

Header (also the accessible name of the handle) and Subheader.

Slider tab

Image "before" – shown left (horizontal) or top (vertical), fitted onto the "after" image.
Image "after" – defines the size of the slider. Use the same aspect ratio for both images. Allowed: gif, jpg, png, svg, webp, avif.
Label "before" / "after" – optional captions on the images; also the alt fallback when the file has no alternative text or title.
Orientation – horizontal (handle moves left/right) or vertical (up/down).
Start position – initial handle position in percent (0–100, default 50).
Load images immediately – disables lazy loading for a slider that is visible without scrolling.

Appearance tab

Header layout, frame class and spacing, as for every core element.

Tab "Slider" of the editing form with the two image fields, labels, orientation, start position and the switch for loading the images immediately — Editing form, tab "Slider".

The slider renders only when both images are set.

Vertical compare slider: the muted image on top, the vivid image below the handle — Vertical orientation.

Accessibility

The handle has role="slider" with aria-valuemin / aria-valuemax / aria-valuenow / aria-valuetext and aria-orientation. Its accessible name is the header (fallback: "Image comparison" / "Bildvergleich").

Arrow keys move the handle by 2 %, Shift + arrow by 10 %, Page Up / Page Down by 10 %, Home / End jump to 0 % / 100 %.
Focus is visible (:focus-visible outline, --cs-focus-color).
Forced-colors mode (Windows High Contrast) keeps the handle visible.
alt texts come from the FAL metadata (alternative, then title), then from the labels. Both images are informative, so give them alternative texts.
Touch: vertical swipes over a horizontal slider scroll the page; horizontal swipes move the handle (touch-action). There are no animations.
Without JavaScript the slider is shown at the start position (browsers with typed attr(); others at 50 %) with the "after" image fully loaded underneath.

Configuration

TypoScript constants and Site Set settings share the same keys:

Constant	Default	Description
`plugin.tx_pxecompareslider.view.templateRootPath`	`EXT:pxe_compareslider/Resources/Private/Templates/ContentElements/`	Directory with your own `Compareslider.html`.
`plugin.tx_pxecompareslider.settings.includeAssetsGlobally`	`0`	`0`: CSS/JS via AssetCollector only on pages with a slider. `1`: site-wide via `page.includeCSS` / `page.includeJSFooter` for themes that concatenate assets (e.g. t3sbootstrap).
`plugin.tx_pxecompareslider.settings.image.maxWidth`	`1540`	Longest edge the images are scaled down to (never upscaled).
`plugin.tx_pxecompareslider.settings.image.srcsetWidths`	`480,768,1024,1540`	Widths for `srcset`; empty disables `srcset`.
`plugin.tx_pxecompareslider.settings.image.sizes`	`100vw`	Value of the `sizes` attribute.

Lazy loading follows styles.content.image.lazyLoading of fluid_styled_content.

Template override

Point plugin.tx_pxecompareslider.view.templateRootPath to a directory of your sitepackage and copy Resources/Private/Templates/ContentElements/Compareslider.html there. The template uses the Default layout and the Header/All partial of fluid_styled_content. Variables: data, flexform, image_before / image_after (FileReference arrays), settings. The ViewHelper cs:srcset(image, widths) builds the srcset string.

Styling

BEM block compareslider. Custom properties on .compareslider: --cs-pos (current position 0–100, written by the script), --cs-handle-color, --cs-handle-width, --cs-knob-size, --cs-focus-color, --cs-label-color, --cs-label-bg.

Labels sit in a corner of their own image: horizontal "before" top left / "after" top right, vertical "before" top left / "after" bottom left. They are covered together with their image when the handle moves over them.

Backend module

The module Compare slider is a top-level entry of the module menu, placed after the page module group (Web in TYPO3 13.4, Content in TYPO3 14). It lists all slider elements of the installation with health checks (missing images, hidden elements) and links to edit each element or open its page. If the optional extension pxe_hub is installed, the module is shown as a card in the hub instead of a top-level module.

The same backend module with German labels — The same module with the backend language set to German.

Upgrading from 2.1.x

Title and subtitle moved from the FlexForm to the core Header / Subheader fields. Existing records keep working: the old FlexForm values are rendered as a caption and used as the handle name while the header field is empty. Sites that relied on the site-wide asset include should set includeAssetsGlobally = 1.

Changelog

See CHANGELOG.md in the repository: https://github.com/pixelegg/pxe-compareslider/blob/main/CHANGELOG.md