Splide
Provides integration with Splide, the lightweight, powerful, and flexible vanilla JavaScript slider library for creating sliders, carousels, and galleries.
splide
Install
composer require 'drupal/splide:^2.0'
Overview
Splide is a Drupal module that integrates the Splide vanilla JavaScript slider library. It provides a powerful and flexible solution for creating responsive image sliders, carousels, and galleries without requiring jQuery.
The module offers multiple ways to create Splide instances: through Field Formatters for image, media, and entity reference fields; Views style plugins for dynamic content; and a text filter for embedding sliders in WYSIWYG content. It features a comprehensive skin system for theming, thumbnail navigation (asNavFor), grid layouts, and supports various media types including images, videos, and audio.
Splide leverages the Blazy module for lazy loading and provides extensive customization through optionsets that can be created and managed via an admin UI. The library supports modern features like loop/fade/slide transitions, autoplay, mouse wheel navigation, fullscreen mode, touch/swipe gestures, and responsive breakpoints.
Features
- Integration with Splide v4.x JavaScript slider library - a lightweight, vanilla JS solution without jQuery dependency
- Multiple display modes: Slider, Carousel, Fade, and Loop transitions
- Field formatters for Image, Media, File, Entity Reference, Paragraphs, and Text fields
- Views style plugins for creating dynamic sliders with optional grouping support
- Text filter for embedding Splide sliders in WYSIWYG content using shortcodes
- Comprehensive skin system with 9+ built-in skins (Default, Classic, Fullscreen, Fullwidth, Grid, Split, Seagreen, Skyblue, etc.)
- Thumbnail navigation (asNavFor) with vertical/horizontal positioning options
- Grid layout support with CSS Grid Foundation for multiple items per slide
- Extensive optionset configuration with 50+ JavaScript options for customization
- Responsive breakpoints with per-breakpoint option overrides
- Autoplay with play/pause controls and progress indicator
- AutoScroll extension integration for continuous scrolling carousels
- Mouse wheel navigation support for accessibility
- Fullscreen mode with zoom capabilities
- Image lazy loading via Blazy module integration
- Support for lightbox integrations (Colorbox, PhotoSwipe, Photobox)
- Touch and swipe gesture support with configurable drag behavior
- Custom arrow and pagination (dots) skin options
- Layout options for caption positioning (14 layouts including split views)
- Override optionset options at the formatter/display level
- Programmatic API with hooks for altering optionsets, options, and attachments
Use Cases
Image Gallery with Thumbnails
Create a main image slider with synchronized thumbnail navigation below. Configure using two optionsets: one for the main display with large images and another for the thumbnail navigation. Set 'Optionset nav' and 'Skin navigation' in the formatter settings. Position thumbnails using the Navigation position option.
Product Image Carousel
Display multiple product images in a carousel format showing 3-4 items at once. Create an optionset with perPage: 3 or 4, type: loop for infinite scrolling, and enable arrows/pagination. Apply the Splide Image formatter to the product image field.
Testimonial Slider
Create an auto-playing testimonial carousel with fade transitions. Use the Splide Text formatter on a multi-value text field, or Splide Entity Reference on a testimonial content type reference. Enable autoplay, set type: fade, and apply the X Testimonial skin from Splide X.
Hero Banner Slideshow
Full-width homepage banners with overlaid text. Use the Fullwidth or Fullscreen skin, enable autoplay with progress indicator, set perPage: 1, and choose appropriate caption layout (center, bottom, etc.). Works with both Image and Media formatters.
Grid Gallery with Lightbox
Display images in a grid that opens in a lightbox. Enable Grid layout with visible items, apply the Grid skin, set Media switch to Colorbox or PhotoSwipe. The grid can be static or paginated with carousel navigation.
Views-based News Slider
Dynamic slider pulling latest news articles. Create a View with Splide Slider format, configure fields for image and title, select optionset and skin. Use grouping optionset for category-based tab navigation.
WYSIWYG Embedded Slider
Allow content editors to embed sliders in body text. Enable the Splide text filter, then use shortcodes like [splide data="node:5:field_gallery" /] to embed existing content's images, or [splide][slide]...[/slide][/splide] for inline HTML slides.
Tips
- Always clone example optionsets and Views from Splide X rather than modifying them directly - updates may revert changes to factory values
- Use the Override main optionset option in formatters to reuse one optionset for multiple displays with slight variations
- For best performance, disable sitewide loading unless specifically needed for body text sliders
- When upgrading, always clear cache and re-save optionsets to pick up new options
- Splide doesn't require Splide UI to run - it's safe to uninstall the UI module once done configuring optionsets
- Combine Grid layout with thumbnail effect for static grid galleries that open in lightbox without carousel navigation
- Use the data attribute in text filter shortcodes for dynamic content: [splide data="node:ID:FIELD_NAME" /]
- For vertical sliders, set Direction to 'ttb' and remember to provide a CSS height for .splide--nav container
Technical Details
Admin Pages 3
/admin/config/media/splide
Configure global Splide settings including CSS options and sitewide loading behavior. This page allows you to enable/disable module CSS files, configure global initialization, and preview slider behavior.
/admin/config/media/splide/optionset
Create, edit, and manage Splide optionsets. Each optionset defines a reusable configuration for slider behavior, appearance, and responsive settings that can be applied to field formatters, Views displays, or text filters.
/admin/config/media/splide/optionset/add
Create a new Splide optionset with customizable settings for slider type, transitions, navigation, autoplay, breakpoints, and advanced options.
Permissions 1
Hooks 4
hook_splide_build_alter
Alter the Splide build array before rendering the slider.
hook_splide_optionset_alter
Alter the optionset configuration before applying to slider.
hook_splide_skins_info
Register custom Splide skins with CSS and JS assets.
hook_splide_overridable_options_info_alter
Alter the list of options that can be overridden in formatters.
Troubleshooting 8
Skins and optionsets are permanently cached. Clear all caches at /admin/config/development/performance or run 'drush cr' to make new items visible.
Re-save optionsets at /admin/config/media/splide and re-save field display settings. Clear cache and regenerate aggregated JS if using aggregation.
Fade transition is designed for single slide view. Change perPage to 1 when using fade mode, or switch to slide/loop type for carousels.
Loop mode creates clone slides which appear in lightboxes. Change type from 'loop' to 'slide' or 'fade' when using Colorbox/PhotoSwipe/Photobox.
Ensure both main and nav optionsets use 'type: loop' or neither uses loop. Disable randomize option on all optionsets. Verify optionset_nav is properly selected.
autoHeight is incompatible with vertical (ttb) direction. Use fixedHeight or heightRatio instead for vertical sliders.
Ensure: 1) Total items > visible_items, 2) Grid skin is selected, 3) perPage and perMove are set to 1 in optionset, 4) Sufficient content exists.
Splide admin CSS may conflict with some admin themes. Disable admin CSS at /admin/config/media/blazy if experiencing display issues.
Security Notes 4
- The module follows Drupal security best practices and has security advisory coverage
- User permissions are properly enforced - only users with 'administer splide' can modify optionsets
- Text filter input is sanitized to prevent XSS attacks in shortcode content
- Always validate and sanitize any custom skin CSS/JS before deployment