Symfony UX Swup

Symfony UX Swup is a Symfony bundle integrating Swup in Symfony applications. It is part of the Symfony UX initiative.

Swup is a complete and easy to use page transition library for Web applications. It creates a Single Page Application feel to Web applications without having to change anything on the server and without bringing the complexity of a React/Vue/Angular application.

Installation

Caution

Before you start, make sure you have StimulusBundle configured in your app.

Install the bundle using Composer and Symfony Flex:

        1
        $ composer require symfony/ux-swup
    

If you're using WebpackEncore, install your assets and restart Encore (not needed if you're using AssetMapper):

        1
2
        $ npm install --force
$ npm run watch
    

Usage

In order to implement page transitions, Swup works by transforming the links of your application in AJAX calls to the target in their href. Once the AJAX call result is received, Swup is able to swap the content of the current page with the new content received by AJAX. When doing this swap, it is therefore able to animate a transition between pages.

The main usage of Symfony UX Swup is to use its Stimulus controller to initialize Swup:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        <html lang="en">
    <head>
        <title>Swup</title>

        {% block javascripts %}
            {{ encore_entry_script_tags('app') }}
        {% endblock %}
    </head>
    <body {{ stimulus_controller('symfony/ux-swup/swup') }}>
        {# ... #}

        <main id="swup">
            {# ... #}
        </main>
    </body>
</html>
    

Note

The stimulus_controller() function comes from StimulusBundle.

That's it! Swup now reacts to a link click and run the default fade-in transition.

By default, Swup will use the #swup selector as a container, meaning it will only swap the content of this container from one page to another. If you wish, you can configure additional containers, for instance to have a navigation menu that updates when changing pages:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
        <html lang="en">
    <head>
        <title>Swup</title>

        {% block javascripts %}
            {{ encore_entry_script_tags('app') }}
        {% endblock %}
    </head>
    <body
        {{ stimulus_controller('symfony/ux-swup/swup', {
            containers: ['#swup', '#nav']
        }) }}
    >
        {# ... #}

        <nav id="nav">
            {# ... #}
        </nav>

        <main id="swup">
            {# ... #}
        </main>
    </body>
</html>
    

You can configure several other options using values on the controller. Most of these correspond to Swup Options, but there are a few extra added:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        <html lang="en">
    <head>
        <title>Swup</title>
    </head>
    <body
        {{ stimulus_controller('symfony/ux-swup/swup', {
            containers: ['#swup', '#nav'],
            animateHistoryBrowsing: true,
            animationSelector: '[class*="transition-"]',
            cache: true,
            linkSelector: '...',

            theme: 'slide',
            debug: true,
        }) }}
    >
        {# ... #}
    </body>
</html>
    

The extra options are:

theme: either slide or fade (the default);
debug: add this attribute to enable debug.

Extend the default behavior

Symfony UX Swup allows you to extend its default behavior using a custom Stimulus controller:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
        // assets/controllers/myswup_controller.js

import { Controller } from '@hotwired/stimulus';
import SwupProgressPlugin from '@swup/progress-plugin';

export default class extends Controller {
    connect() {
        this.element.addEventListener('swup:pre-connect', this._onPreConnect);
        this.element.addEventListener('swup:connect', this._onConnect);
    }

    disconnect() {
        // You should always remove listeners when the controller is disconnected to avoid side-effects
        this.element.removeEventListener('swup:connect', this._onConnect);
        this.element.removeEventListener('swup:pre-connect', this._onPreConnect);
    }

    _onPreConnect(event) {
        // Swup has not been initialized - options can be changed
        console.log(event.detail.options); // Options that will be used to initialize Swup
        event.detail.options.plugins.push(new SwupProgressPlugin()); // Adding the progress bar plugin
    }

    _onConnect(event) {
        // Swup has just been intialized and you can access details from the event
        console.log(event.detail.swup); // Swup instance
        console.log(event.detail.options); // Options used to initialize Swup
    }
}
    

Then in your template, add your controller to the HTML attribute:

        1
2
3
4
5
6
7
8
9
10
11
        <html lang="en">
    <head>
        <title>Swup</title>
        {# ... #}
    </head>
    <body {{ stimulus_controller('myswup')|stimulus_controller('symfony/ux-swup/swup', {
        // ... options
    }) }}>
        {# ... #}
    </body>
</html>
    

Note

Be careful to add your controller before the Swup controller so that it is executed before and can listen on the swup:connect event properly.

Backward Compatibility promise

This bundle aims at following the same Backward Compatibility promise as the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.

TOC

Version

Show your Symfony expertise

Save your teams and projects before they sink