swup

Transform your Drupal site into a smooth, app-like experience with Swup.js integration. Enable seamless page transitions without full reloads, dramatically improving perceived performance and user engagement.

Features

Core Functionality:

• Instant Page Transitions: Navigate between pages without full browser reloads, creating a Single Page Application (SPA) feel while maintaining traditional server-rendered architecture
• Smart Caching: Automatically caches visited pages for instant back/forward navigation
• Progressive Enhancement: Works with existing Drupal sites without requiring architectural changes
• Zero jQuery Dependency: Pure vanilla JavaScript, lightweight (~10KB core)

Unique Capabilities:

• 14 Official Plugins: Accessibility, forms handling, preloading, progress bars, animations, and more
• Drupal-Optimized: Automatically excludes admin pages, edit forms, and AJAX operations
• Multi-Theme Support: Configure different behaviors for different themes
• Flexible CDN/Local Loading: Use CDN for quick setup or local installation for production

Use Cases:

• Portfolio and agency websites requiring polished, professional navigation
• Content-heavy sites where perceived performance matters
• Mobile-first experiences demanding app-like interactions
• Sites with complex animations between page sections
• Multi-language sites needing smooth locale switching

Post-Installation

Quick Start (5 minutes):

1. Enable the module: drush en swup -y
2. Visit any non-admin page - Swup loads automatically via CDN
3. Click internal links to see instant transitions

Advanced Configuration:

1. Enable the UI submodule: drush en swup_ui -y
2. Navigate to Configuration > User Interface > Swup (/admin/config/user-interface/swup/settings)
3. Configure:
   • CDN Provider: Choose between unpkg or jsDelivr
   • Plugins: Enable accessibility, preloading, animations, etc.
   • Theme Restrictions: Limit to specific themes
   • Path Exclusions: Fine-tune where Swup loads

Adding Animations (in your theme's JS):

Drupal.behaviors.swupCustom = {
  attach: function() {
    if (typeof Swup !== 'undefined') {
      const swup = new Swup({
        containers: ['#main-content'],
        animationSelector: '[class*="transition-"]'
      });
    }
  }
};

Additional Requirements

No external dependencies required! The module works out-of-the-box using CDN delivery.

For Local Installation (Optional):

# Configure composer.json
composer config repositories.assets composer https://asset-packagist.org
composer config extra.installer-types.0 npm-asset
composer config extra.installer-paths.web/libraries/\{\$name\} type:npm-asset

# Install packages
composer require oomphinc/composer-installers-extender npm-asset/swup

Server Requirements:

• Drupal 9.5, 10, or 11
• Modern browsers (Chrome 61+, Firefox 60+, Safari 11+, Edge 79+)
• Older browsers gracefully fallback to standard navigation

Official Swup Plugins (included):

• Accessibility Plugin - Screen reader support and focus management
• Preload Plugin - Hover preloading for instant navigation
• Head Plugin - Meta tag and asset updates
• Forms Plugin - AJAX form submissions
• Debug Plugin - Development and debugging tools
• Progress Bar Plugin - Visual loading indicators
• Scroll Plugin - Smooth scrolling with custom offsets
• And 7 more plugins available through the UI

Similar projects

Barba JS

Barba JS integrates the Barba.js library with Drupal to deliver smooth, SPA-like page transitions with minimal setup. It auto-loads a local build when present, or falls back to the official CDN. The optional UI submodule lets you control where and how the library is attached.

Swup advantages: Larger plugin ecosystem (14 official plugins vs 4), better documentation, more active development, built-in accessibility features, lighter core library.

Supporting this Module

Get Help:

• Issue Queue - Report bugs and request features
• Drupal Slack #frontend - Chat with the community
• Maintainer: mahyarsbt

Contribute:

• Submit patches and merge requests
• Report bugs and feature requests
• Improve documentation
• Share your Swup implementations

Community Documentation

Official Resources:

• Swup.js Documentation - Complete API reference
• Interactive Demos - Live examples
• Video Tutorials - Step-by-step guides
• GitHub Repository - Source code and issues

Drupal-Specific Guides:

• Getting Started with Swup
• Creating Custom Animations
• Plugin Configuration Guide
• Troubleshooting Common Issues
• Showcase Gallery - Sites using Swup

Why Choose Swup for Drupal?

Swup bridges the gap between traditional server-rendered Drupal sites and modern SPA experiences. Unlike heavy JavaScript frameworks, Swup enhances your existing Drupal site without requiring a complete rebuild. It respects Drupal's architecture while delivering the smooth, instant navigation users expect from modern web applications.

Perfect for agencies and developers who want to deliver premium user experiences without the complexity of decoupled architectures. Your content editors keep using Drupal's familiar interface while your visitors enjoy app-like navigation.

Version Compatibility: This module supports Swup 4.x, the latest major version with significant performance improvements and a modern plugin architecture.