Symfony UX 2.0 & Stimulus 3 Support

Symfony UX is an initiative and set of libraries centered around the
Stimulus JavaScript library. And today, I’m pleased to announce several
new releases:

Version 2.0 of all symfony/ux libraries
Version 3.0 of @symfony/stimulus-bridge
Version 2.0 of @symfony/stimulus-testing

What does this all mean? Let’s find out!

Stimulus 3 Support

Stimulus 3.0 – a new major version – was released in September. It includes
a few nice new features – like a „debug“ mode and „values defaults“ – but no
major changes and no backwards compatibility breaks.

So why the new major version? Because the library was renamed from stimulus
to @hotwired/stimulus. Yup, the name of the library changed… but not much
else. However, the name change required Symfony’s UX libraries to need a new
major version.

Symfony UX Changes

There are 4 big changes with the new Symfony UX releases:

1) Support changed from stimulus to @hotwired/stimulus

The biggest change with the new major releases listed above is that support for
stimulus was dropped and replaced with @hotwired/stimulus (i.e. version
3 of the library). This difference won’t be noticeable in your applications,
except that you’ll need to adjust the import { Controller } from ’stimulus‘
lines in your code (see about upgrading below).

2) Support for IE11 was dropped

Version 3 of Stimulus dropped support for IE11. We did the same thing in our
Symfony UX libraries and incorporated a brand new build system. The result is
smaller final JavaScript sizes. If you need to continue supporting IE 11, use
Stimulus 2 and the previous version of the UX libraries.

3) data- Attributes Changed to the Values API

Many of the UX packages allowed you to configure things by adding data- attributes
to an element. Those have been replaced by using the „Values API“ from Stimulus,
which is a bit nicer anyways. For example, if you use symfony/ux-lazy-image,
then previously the code looked like this:

{# Code for the old, 1.x version #}
{{ asset(‚image/small.png‘) }}
{{ stimulus_controller(’symfony/ux-lazy-image/lazy-image‘) }}
{{ asset(‚image/large.png‘) }}

This code would now need to be updated to this:

{# Code for the new, 2.x version #}
{{ asset(‚image/small.png‘) }}
{{ stimulus_controller(’symfony/ux-lazy-image/lazy-image‘, {
src: asset(‚image/large.png‘)
}) }}


See the README – or CHANGELOG (e.g. Lazy Image CHANGELOG) – of each library for
a full set of changes.

In addition to the above items, symfony/ux-chartjs was updated to use chart.js
version 3, and various new events were added to UX controllers to make them more

How do I Upgrade?

To upgrade, you’ll need to update a number of packages at the same time and make
an adjustment to each Stimulus controller in your project:

Remove stimulus from your package.json file and replace it with
„@hotwired/stimulus“: „^3.0“. Also change your @symfony/webpack-encore
version to ^1.7 and @symfony/stimulus-bridge to ^3.0. After making
these changes, run yarn install.

Update all of your controllers to replace any imports for stimulus with
imports from @hotwired/stimulus:

-import { Controller } from ’stimulus‘;

+import { Controller } from ‚@hotwired/stimulus‘;

In composer.json, update any symfony/ux-* packages that you have installed
to version ^2.0. Run composer up „symfony/ux-*“. Once that finishes,
run yarn install –force.

And… that’s it! Congratulations on upgrading to Stimulus 3.

Happy UX’ing!

Sponsor the Symfony project.

Symfony Blog
Read More

Latest News


PHP 8.2.16 released!

PHP 8.3.3 released!

PHP 8.1.27 released!

Generated by Feedzy