StimulusBundle: Symfony integration with Stimulus

TypeScript Controllers

If you want to use TypeScript to define your controllers, you can! Install and set up the sensiolabs/typescript-bundle. Then be sure to add the assets/controllers path to the sensiolabs_typescript.source_dir configuration. Finally, create your controller in that directory and you're good to go.

The UX Packages

Symfony provides a set of UX packages that add extra Stimulus controllers to solve common problems. StimulusBundle activates any 3rd party Stimulus controllers that are mentioned in your assets/controllers.json file. This file is updated whenever you install a UX package.

Check out the official UX packages.

Lazy Stimulus Controllers

By default, all of your controllers (i.e. files in assets/controllers/ + controllers in assets/controllers.json) will be downloaded and loaded on every page.

Sometimes you may have a controller that's only used on some pages. In that case, you can make the controller "lazy". In this case, will not be downloaded on initial page load. Instead, as soon as an element appears on the page matching the controller (e.g. <div data-controller="hello">), the controller - and anything else it imports - will be lazily-loaded via Ajax.

To make one of your custom controllers lazy, add a special comment on top:

1
2
3
4
5
6

import { Controller } from '@hotwired/stimulus';

/* stimulusFetch: 'lazy' */
export default class extends Controller {
    // ...
}

To make a third-party controller lazy, in assets/controllers.json, set fetch to lazy.

stimulus_controller

This bundle ships with a special stimulus_controller() Twig function that can be used to render Stimulus Controllers & Values and CSS Classes. Stimulus Controllers can also reference other controllers by using Outlets.

For example:

1
2
3
4
5
6
7
8
9
10
11
12

<div {{ stimulus_controller('hello', { 'name': 'World', 'data': [1, 2, 3, 4] }) }}>
    Hello
</div>

<!-- would render -->
<div
   data-controller="hello"
   data-hello-name-value="World"
   data-hello-data-value="&#x5B;1,2,3,4&#x5D;"
>
   Hello
</div>

If you want to set CSS classes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<div {{ stimulus_controller('hello', { 'name': 'World', 'data': [1, 2, 3, 4] }, { 'loading': 'spinner' }) }}>
    Hello
</div>

<!-- would render -->
<div
   data-controller="hello"
   data-hello-name-value="World"
   data-hello-data-value="&#x5B;1,2,3,4&#x5D;"
   data-hello-loading-class="spinner"
>
   Hello
</div>

<!-- or without values -->
<div {{ stimulus_controller('hello', controllerClasses: { 'loading': 'spinner' }) }}>
    Hello
</div>

And with outlets:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<div {{ stimulus_controller('hello',
        { 'name': 'World', 'data': [1, 2, 3, 4] },
        { 'loading': 'spinner' },
        { 'other': '.target' } ) }}>
    Hello
</div>

<!-- would render -->
<div
   data-controller="hello"
   data-hello-name-value="World"
   data-hello-data-value="&#x5B;1,2,3,4&#x5D;"
   data-hello-loading-class="spinner"
   data-hello-other-outlet=".target"
>
   Hello
</div>

<!-- or without values/classes -->
<div {{ stimulus_controller('hello', controllerOutlets: { 'other': '.target' }) }}>
    Hello
</div>

Any non-scalar values (like data: [1, 2, 3, 4]) are JSON-encoded. And all values are properly escaped (the string [ is an escaped [ character, so the attribute is really [1,2,3,4]).

If you have multiple controllers on the same element, you can chain them as there's also a stimulus_controller filter:

1
2
3
4
5
6
7
8

<div {{ stimulus_controller('hello', { 'name': 'World' })|stimulus_controller('other-controller') }}>
    Hello
</div>

<!-- would render -->
<div data-controller="hello other-controller" data-hello-name-value="World">
    Hello
</div>

You can also retrieve the generated attributes as an array, which can be helpful e.g. for forms:

1

{{ form_start(form, { attr: stimulus_controller('hello', { 'name': 'World' }).toArray() }) }}

stimulus_action

The stimulus_action() Twig function can be used to render Stimulus Actions.

For example:

1
2
3
4
5
6

<div {{ stimulus_action('controller', 'method') }}>Hello</div>
<div {{ stimulus_action('controller', 'method', 'click') }}>Hello</div>

<!-- would render -->
<div data-action="controller#method">Hello</div>
<div data-action="click->controller#method">Hello</div>

If you have multiple actions and/or methods on the same element, you can chain them as there's also a stimulus_action filter:

1
2
3
4
5
6
7
8

<div {{ stimulus_action('controller', 'method')|stimulus_action('other-controller', 'test') }}>
    Hello
</div>

<!-- would render -->
<div data-action="controller#method other-controller#test">
    Hello
</div>

You can also retrieve the generated attributes as an array, which can be helpful e.g. for forms:

1

{{ form_row(form.password, { attr: stimulus_action('hello-controller', 'checkPasswordStrength').toArray() }) }}

You can also pass parameters to actions:

1
2
3
4

<div {{ stimulus_action('hello-controller', 'method', 'click', { 'count': 3 }) }}>Hello</div>

<!-- would render -->
<div data-action="click->hello-controller#method" data-hello-controller-count-param="3">Hello</div>

stimulus_target

The stimulus_target() Twig function can be used to render Stimulus Targets.

For example:

1
2
3
4
5
6

<div {{ stimulus_target('controller', 'myTarget') }}>Hello</div>
<div {{ stimulus_target('controller', 'myTarget secondTarget') }}>Hello</div>

<!-- would render -->
<div data-controller-target="myTarget">Hello</div>
<div data-controller-target="myTarget secondTarget">Hello</div>

If you have multiple targets on the same element, you can chain them as there's also a stimulus_target filter:

1
2
3
4
5
6
7
8

<div {{ stimulus_target('controller', 'myTarget')|stimulus_target('other-controller', 'anotherTarget') }}>
    Hello
</div>

<!-- would render -->
<div data-controller-target="myTarget" data-other-controller-target="anotherTarget">
    Hello
</div>

You can also retrieve the generated attributes as an array, which can be helpful e.g. for forms:

1

{{ form_row(form.password, { attr: stimulus_target('hello-controller', 'myTarget').toArray() }) }}

Chaining Different Helpers

The stimulus_controller, stimulus_action and stimulus_target filters can be mixed freely to render all the attributes of an element at once, whichever function the chain started with:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<div {{ stimulus_controller('first-controller')
    |stimulus_target('second-controller', 'anotherTarget')
    |stimulus_target('third-controller', 'foo')
    |stimulus_action('first-controller', 'test')
    |stimulus_controller('fourth-controller')
    |stimulus_action('fourth-controller', 'onClick') }}
>
    Hello
</div>

<!-- would render -->
<div data-controller="first-controller fourth-controller"
    data-action="first-controller#test fourth-controller#onClick"
    data-second-controller-target="anotherTarget"
    data-third-controller-target="foo"
>
    Hello
</div>

With AssetMapper

If you're using AssetMapper, two new entries will be added to your importmap.php file:

1
2
3
4
5
6
7
8
9
10
11

// importmap.php
return [
    // ...

    '@symfony/stimulus-bundle' => [
        'path' => '@symfony/stimulus-bundle/loader.js',
    ],
    '@hotwired/stimulus' => [
        'version' => '3.2.2',
    ],
];

The recipe will update your assets/stimulus_bootstrap.js file to look like this:

1
2
3
4

// assets/stimulus_bootstrap.js
import { startStimulusApp } from '@symfony/stimulus-bundle';

const app = startStimulusApp();

The @symfony/stimulus-bundle refers the one of the new entries in your importmap.php file. This file is dynamically built by the bundle and will import all your custom controllers as well as those from controllers.json. It will also dynamically enable "debug" mode in Stimulus when your application is running in debug mode.

With WebpackEncoreBundle

If you're using Webpack Encore, the recipe will also update your webpack.config.js file to include this line:

1
2

// webpack.config.js
.enableStimulusBridge('./assets/controllers.json')

The assets/stimulus_bootstrap.js file will be updated to look like this:

1
2
3
4
5
6
7
8
9

// assets/stimulus_bootstrap.js
import { startStimulusApp } from '@symfony/stimulus-bridge';

// Registers Stimulus controllers from controllers.json and in the controllers/ directory
export const app = startStimulusApp(require.context(
    '@symfony/stimulus-bridge/lazy-controller-loader!./controllers',
    true,
    /\.[jt]sx?$/
));

The @hotwired/stimulus package will be added to your package.json file. The Webpack Encore integration also relies on @symfony/stimulus-bridge, which is specific to Encore, so install it yourself:

1

$ npm install --save-dev @symfony/stimulus-bridge

With Reprise

If you're using Reprise, you must enable Stimulus by pointing the Reprise plugin at your controllers.json file:

1
2
3
4
5
6
7
8
9
10

// vite.config.js (or rsbuild.config.js)
import Symfony from '@symfony/reprise/vite';

export default defineConfig({
    plugins: [
        Symfony({
            stimulus: './assets/controllers.json',
        }),
    ],
});

The assets/stimulus_bootstrap.js file will be updated to look like this:

1
2
3
4

// assets/stimulus_bootstrap.js
import { startStimulusApp } from '@symfony/reprise/stimulus';

const app = startStimulusApp();

The @symfony/reprise/stimulus helper starts the application and registers all your custom controllers along with those from controllers.json, eager or lazy, the same way the AssetMapper loader does. The Stimulus runtime ships with the @symfony/reprise package, so @hotwired/stimulus is the only extra package you need to install.

Scoping Controllers with Reprise

startStimulusApp() from @symfony/reprise/stimulus takes no arguments, like the AssetMapper one. What it reads is generated by the Reprise plugin, and that generation is configurable, so each build can be given its own set of controllers.

If a single config defines several entry points, they all share the same controller set, because there is only one plugin instance. To scope controllers to a given area of your application, give that area its own build config and point the plugin at its own controllers directory. For example, an admin area could use a dedicated config like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// vite.config.admin.ts  -- run with `vite build --config vite.config.admin.ts`
import { defineConfig } from 'vite'
import Symfony from '@symfony/reprise/vite'

export default defineConfig({
  input: {
    admin: './assets/admin.js',
  },
  plugins: [
    Symfony({
      outputPath: 'public/admin-build',
      publicPath: '/admin-build/',
      stimulus: {
        controllersJson: 'assets/admin/controllers.json',
        controllersDir: 'assets/admin/controllers',
      },
    }),
  ],
})

This entry point then starts the application the usual way:

1
2
3
4

// assets/admin.js
import { startStimulusApp } from '@symfony/reprise/stimulus'

const app = startStimulusApp()

Register this build on the PHP side under reprise.builds so the Twig tag functions can address it with a build argument.

See the Reprise Stimulus documentation for what else the returned application lets you do, such as registering controllers that are not declared in controllers.json.

Scoping Controllers with Webpack Encore

startStimulusApp() from @symfony/stimulus-bridge accepts a Webpack context, so you can point each entry at its own controller directory. This assets/admin.js file loads only the controllers under controllers/admin:

1
2
3
4
5
6
7

import { startStimulusApp } from '@symfony/stimulus-bridge';

export const app = startStimulusApp(require.context(
    '@symfony/stimulus-bridge/lazy-controller-loader!./controllers/admin',
    true,
    /\.[jt]sx?$/
));

If you keep the controllers shared between areas in their own directory, you can load several contexts into the same application:

1
2
3
4
5
6
7

import { startStimulusApp } from '@symfony/stimulus-bridge';
import { definitionsFromContext } from '@hotwired/stimulus-webpack-helpers';

const app = startStimulusApp();

app.load(definitionsFromContext(require.context('./controllers/common', true)));
app.load(definitionsFromContext(require.context('./controllers/admin', true)));

This second form drops the lazy controller loader, so add it back to the context path if you rely on lazy loading.

If you need this with AssetMapper, follow the discussion in issue #2321 in the symfony/ux repository.