Swiper formatter
Integrates Swiper.js, a modern mobile-first swiping/sliding library, as field formatters and Views style plugin for Drupal.
swiper_formatter
Install
composer require 'drupal/swiper_formatter:^2.0'
composer require 'drupal/swiper_formatter:^1.0'
Overview
Swiper formatter provides Drupal integration with Swiper.js, one of the most modern and feature-rich swiping/sliding libraries available. Unlike traditional image sliders, this module is designed as a comprehensive swiping UI widget that can handle almost any kind of content.
The module supports horizontal and vertical sliding directions and works with various field types including images, text/markup fields, media references, entity references, paragraphs, and Views results. It offers a configuration entity system that allows creating reusable "Swiper templates" with customizable options for navigation, pagination, autoplay, lazy loading, grid layouts, breakpoints, and many more Swiper.js features.
Content can be displayed in regular Swiper format or with dialog/modal functionality, where clicking a slide opens the content in a modal, off-canvas, or dialog overlay.
Features
- Configuration entity system for creating reusable Swiper templates with extensive customization options
- Multiple field formatters: Swiper images, Swiper markup (text), Swiper entity (entity references), Swiper Paragraphs (paragraphs)
- Dialog variants for all formatters that open content in modal, dialog, or off-canvas overlays
- Views style plugin for displaying any Views results as a Swiper slider
- Support for Swiper.js modules: Navigation, Pagination, Scrollbar, Autoplay, Lazy Loading, and Grid
- Responsive breakpoint support with ability to reference other Swiper templates for different viewport sizes
- Multiple library source options: bundled package, remote CDN, or local installation
- Caption support from various field sources including image alt/title and other text fields
- Slide transition effects: slide, fade, cube, coverflow, flip, and cards
- Token integration for dynamic dialog titles and custom links
- Extensive theme suggestion system for template customization per view, entity type, field, or view mode
- Hook for programmatically altering Swiper settings before rendering
Use Cases
Image Gallery with Lazy Loading
Use the Swiper images formatter on a multi-value image field to create a responsive image gallery. Enable lazy loading in the Swiper template to improve page load performance. Configure slidesPerView to show multiple thumbnails and enable navigation and pagination for easy browsing.
Content Carousel on Homepage
Create a Views block displaying featured content nodes and use the Swiper formatter style plugin. Configure autoplay with a delay of 5000ms for automatic cycling through featured items. Each view result row becomes a slide showing the rendered content in a specified view mode.
Product Image Lightbox
Use the Swiper images Dialog formatter on a product's image field. Configure the dialog to open as a modal showing a larger image style. Users can click thumbnails in the Swiper to view full-size images in a modal overlay.
Testimonials Slider with Text
Create a multi-value text_long field for testimonials and apply the Swiper markup formatter. Enable autoplay for automatic cycling and use the fade effect for smooth transitions between testimonials.
Responsive Breakpoint Configuration
Create multiple Swiper templates: one main template and separate breakpoint templates for different viewport sizes (e.g., 480px, 960px). Configure the main template to reference breakpoint templates, adjusting slidesPerView and navigation visibility for each screen size. The module follows mobile-first approach where breakpoint operators are >= the specified width.
Paragraph Slider
Add a Paragraphs field to a content type for creating slide content with rich formatting. Apply the Swiper Paragraphs formatter to display each paragraph item as a slide. This allows content editors to create slides with custom layouts, images, text, and other paragraph components.
Media Gallery with Modal Preview
Use the Swiper entity Dialog formatter on an entity reference field pointing to Media entities. Configure slides to show thumbnail view mode and dialog to show full view mode. Users can browse thumbnails and click to open a larger preview in a modal or off-canvas panel.
Tips
- Create dedicated Swiper templates for different use cases (e.g., 'Hero slider', 'Product gallery', 'Testimonials') to maintain consistent configurations across the site.
- Use the 'Package' library source for production sites to bundle Swiper.js with your module and avoid external CDN dependencies.
- For vertical sliders, set a fixed height in the Swiper template and enable autoHeight.
- When using CSS mode for better performance, note that some Swiper features like transition effects other than slide are not supported.
- Use the hook_swiper_formatter_settings_alter to dynamically adjust settings based on the number of slides or other runtime conditions.
- Template suggestions allow creating custom Twig templates per view, content type, field name, or specific Swiper template for fine-grained control over markup.
- The observer option is useful when Swiper is inside a hidden container (tabs, accordions) that becomes visible after page load.
- For production sites with performance concerns, consider using local minified library source and enabling lazy loading for image-heavy sliders.
Technical Details
Admin Pages 3
/admin/config/content/swiper-formatter
Lists all existing Swiper templates (configuration entities). From here you can view, edit, or delete templates, and create new ones. The default template cannot be deleted.
/admin/config/content/swiper_formatter/add
Creates a new Swiper configuration template with customizable Swiper.js parameters and modules.
/admin/config/content/swiper-formatter/{swiper_formatter}
Edit an existing Swiper configuration template.
Permissions 1
Hooks 1
hook_swiper_formatter_settings_alter
Allows altering Swiper formatter settings before rendering. Can be used to dynamically modify slidesPerView, grid settings, or any other Swiper option.
Troubleshooting 6
Check that the Swiper template is enabled (not disabled). Verify the library source is accessible - if using local, ensure files are placed in /libraries/swiper/. Check browser console for JavaScript errors. Make sure there are at least 2 slides, as Swiper is skipped for single-item fields.
Ensure navigation and/or pagination modules are enabled in the Swiper template configuration. Check that the template selected on the field formatter matches a template with these features enabled.
Verify lazy loading is enabled in the Swiper template. For Views, ensure the image field has an image style configured. The module sets preloadImages: false and watchSlidesProgress: true automatically when lazy loading is enabled.
Ensure the appropriate Drupal Ajax library is loaded. For modals, core/drupal.dialog.ajax is required; for off-canvas, core/drupal.dialog.off_canvas is needed. The module should attach these automatically. Check that the entity the dialog is trying to load exists and is accessible.
Remember Swiper uses mobile-first approach - breakpoints apply at >= the specified width. Ensure breakpoint templates are marked as 'Breakpoint template' so they don't appear in normal formatter selections. The breakpoint value should be numeric (pixels) or start with @ for percentage values.
Swiper formatters only apply to multi-value fields (cardinality > 1). For entity reference fields, ensure the field storage allows multiple values. Single-value fields cannot use Swiper formatters.