Symfony Stimulus Bundle

https://symfony.com/bundles/StimulusBundle/current/
Admin
StimulusBundle adds Symfony integration with Stimulus, providing Twig functions and filters to add...
Tokens:9,006
Snippets:76
Trust Score:9.7
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install StimulusBundle with Composer

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Run this command to install the symfony/stimulus-bundle package. If using Symfony Flex, the recipe will update necessary files automatically.

```bash
$ composer require symfony/stimulus-bundle
```

--------------------------------

### Create a custom Stimulus controller in assets/controllers/hello_controller.js

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Example controller that sets the element's text content on connect. Place this file in assets/controllers/hello_controller.js.

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

export default class extends Controller {
    connect() {
        this.element.textContent = 'Hello Stimulus! Edit me in assets/controllers/hello_controller.js';
    }
}
```

--------------------------------

### Install @symfony/stimulus-bridge via npm

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

The Webpack Encore integration relies on @symfony/stimulus-bridge, which is specific to Encore, so install it yourself.

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

--------------------------------

### AssetMapper stimulus_bootstrap.js

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

The recipe updates assets/stimulus_bootstrap.js to import startStimulusApp from '@symfony/stimulus-bundle' and start the app.

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

const app = startStimulusApp();
```

--------------------------------

### Reprise entry point for admin area (assets/admin.js)

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Entry point that starts the Stimulus application for the admin area using `startStimulusApp()` from `@symfony/reprise/stimulus`. This is used with the dedicated Vite config to load only the admin controllers.

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

const app = startStimulusApp()
```

--------------------------------

### Reprise stimulus_bootstrap.js

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

The assets/stimulus_bootstrap.js file is updated to import startStimulusApp from '@symfony/reprise/stimulus' and start the app.

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

const app = startStimulusApp();
```

--------------------------------

### Chaining different Stimulus helpers

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Shows how to mix stimulus_controller, stimulus_action, and stimulus_target filters to render all attributes at once, regardless of the starting function.

```twig
<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>
```

--------------------------------

### stimulus_action() with parameters

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Passes parameters to actions. The example shows a 'count' parameter rendered as a data attribute.

```twig
<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() function usage

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Renders data-controller-target attributes. The first example shows single and multiple targets. The second example shows chaining with the stimulus_target filter.

```twig
<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>
```

```twig
<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>
```

--------------------------------

### stimulus_action() function usage

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Renders data-action attributes for Stimulus actions. The first example shows default event (no event specified) and explicit 'click' event. The second example shows chaining with the stimulus_action filter.

```twig
<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>
```

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

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

--------------------------------

### Retrieve attributes as array for forms

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Uses the toArray() method to get the generated attributes as an array, which can be passed to form_start's attr option.

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

--------------------------------

### Rendered HTML attributes for the country-picker controller

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

The HTML output produced by the form field when using the Stimulus attributes from the PHP example. Shows the data-controller, data-action, data-target, and data-value attributes.

```html
<select
    data-controller="country-picker"
    data-action="change->country-picker#refresh"
    data-country-picker-target="select"
    data-country-picker-locale-value="fr"
>
```

--------------------------------

### Activate the controller in HTML with data-controller

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

HTML element that activates the hello controller when it appears on the page.

```html
<div data-controller="hello">
   ...
</div>
```

--------------------------------

### Chaining Different Helpers

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Demonstrates mixing stimulus_controller, stimulus_action, and stimulus_target filters to render all attributes at once.

```APIDOC
## Chaining Different Helpers

### Description
Demonstrates how to mix `stimulus_controller`, `stimulus_action`, and `stimulus_target` filters to render all attributes of an element at once, regardless of the starting filter.

### Usage
Chain any of the filters together in any order.

### Example
```twig
<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>
```

### Rendered Output
```html
<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>
```
```

--------------------------------

### stimulus_controller() with outlets

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Renders a Stimulus controller with outlets. Shows the full syntax with values, classes, and outlets, and a variant without values/classes using the named argument controllerOutlets.

```html
<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>
```

--------------------------------

### StimulusBundle configuration in config/packages/stimulus.yaml

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Configure the paths to your controllers directory and the controllers.json file if you need different paths. The default values are shown.

```yaml
# config/packages/stimulus.yaml
stimulus:
    # the default values
    controller_paths:
        - '%kernel.project_dir%/assets/controllers'
    controllers_json: '%kernel.project_dir%/assets/controllers.json'
```

--------------------------------

### Webpack Encore stimulus_bootstrap.js

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

The recipe updates assets/stimulus_bootstrap.js to use startStimulusApp from '@symfony/stimulus-bridge' and register controllers from controllers.json and the controllers directory.

```javascript
// 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?$/
));
```

--------------------------------

### Webpack Encore: load multiple contexts into one app

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Loads controllers from both `./controllers/common` and `./controllers/admin` into the same Stimulus application using `definitionsFromContext` from `@hotwired/stimulus-webpack-helpers`. Note that this form drops the lazy controller loader, so add it back if lazy loading is needed.

```javascript
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)));
```

--------------------------------

### stimulus_controller() with CSS classes

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Renders a Stimulus controller with CSS classes. Shows the full syntax with values and classes, and a variant without values using the named argument controllerClasses.

```html
<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>
```

--------------------------------

### Webpack Encore: load controllers from a single context (assets/admin.js)

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

This `assets/admin.js` file uses `startStimulusApp()` from `@symfony/stimulus-bridge` with a Webpack context to load only controllers under `controllers/admin`. The context uses the lazy-controller-loader.

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

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

--------------------------------

### assets/controllers.json with @symfony/ux-chartjs controller

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Shows the controller registration added by the Flex recipe, enabling the chart controller with eager fetch.

```json
{
    "controllers": {
        "@symfony/ux-chartjs": {
            "chart": {
                "enabled": true,
                "fetch": "eager"
            }
        }
    },
    "entrypoints": []
}
```

--------------------------------

### Reprise vite.config.js (or rsbuild.config.js) stimulus configuration

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

When using Reprise, enable Stimulus by pointing the Reprise plugin at your controllers.json file.

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

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

--------------------------------

### stimulus_controller() with @symfony/ux-chartjs/chart

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Shows how to use the stimulus_controller() function with the original controller name, which is normalized to the Stimulus format. The rendered HTML is shown as a comment.

```html
<div {{ stimulus_controller('@symfony/ux-chartjs/chart') }}>

<!-- will render as: -->
<div data-controller="symfony--ux-chartjs--chart">
```

--------------------------------

### Make a custom controller lazy with stimulusFetch comment

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Add the comment /* stimulusFetch: 'lazy' */ to the top of the controller file to make it lazy. The controller will not be downloaded on initial page load, but loaded via Ajax when an element matching it appears.

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

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

--------------------------------

### Reprise Vite config for admin area (vite.config.admin.ts)

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Dedicated Vite config for an admin area, run with `vite build --config vite.config.admin.ts`. It sets the input to `./assets/admin.js`, output path to `public/admin-build`, public path to `/admin-build/`, and configures the Stimulus plugin to use `assets/admin/controllers.json` and `assets/admin/controllers`.

```typescript
// 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',
      },
    }),
  ],
})
```

--------------------------------

### AssetMapper importmap.php entries for StimulusBundle

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

When using AssetMapper, two new entries are added to importmap.php: one for '@symfony/stimulus-bundle' and one for '@hotwired/stimulus'.

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

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

--------------------------------

### stimulus_controller() with values

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Renders a Stimulus controller with values. Non-scalar values like arrays are JSON-encoded and escaped, as shown in the rendered output.

```html
<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>
```

--------------------------------

### package.json devDependencies with @symfony/ux-chartjs

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Shows the virtual package entry added by Symfony Flex to package.json, pointing to the assets directory in the vendor folder. This is not needed when using AssetMapper.

```json
{
    "devDependencies": {
        "...": "",
        "@symfony/ux-chartjs": "file:vendor/symfony/ux-chartjs/assets"
    }
}
```

--------------------------------

### stimulus_action()

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Renders a Stimulus action attribute. Supports optional event and parameters. Can be used as a function or filter, and returns an object with a toArray() method.

```APIDOC
## stimulus_action()

### Description
Renders a Stimulus action attribute. Can be used as a Twig function or filter. Supports optional event and parameters. Returns an object with a `toArray()` method for retrieving attributes as an array.

### Method
Twig Function/Filter

### Usage
- `stimulus_action(controller, method, event?, parameters?)`
- `stimulus_action(controller, method)|stimulus_action(otherController, otherMethod)`

### Parameters
- **controller** (string) - Required - The Stimulus controller identifier.
- **method** (string) - Required - The action method name.
- **event** (string) - Optional - The DOM event to trigger the action (e.g., 'click'). Defaults to no event.
- **parameters** (array) - Optional - Action parameters as key-value pairs.

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

### Rendered Output
```html
<div data-action="controller#method">Hello</div>
<div data-action="click->controller#method">Hello</div>
<div data-action="click->hello-controller#method" data-hello-controller-count-param="3">Hello</div>
```

### Chaining Example
```twig
<div {{ stimulus_action('controller', 'method')|stimulus_action('other-controller', 'test') }}>
    Hello
</div>
```

### Rendered Output
```html
<div data-action="controller#method other-controller#test">
    Hello
</div>
```

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

--------------------------------

### Use stimulus_controller Twig function to render the data-controller attribute

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Twig template using the stimulus_controller function, which renders the data-controller attribute. The comment shows the rendered output.

```twig
<div {{ stimulus_controller('hello') }}>
    ...
</div>

<!-- would render -->
<div data-controller="hello">
   ...
</div>
```

--------------------------------

### Create Stimulus attributes in a form with StimulusHelper

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Use the StimulusHelper service to create Stimulus attributes for a form field. Add a controller, target, and action, then pass the attributes to the form field's 'attr' option.

```php
// src/Form/EventType.php
namespace App\Form;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\CountryType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\UX\StimulusBundle\Helper\StimulusHelper;

class EventType extends AbstractType
{
    public function __construct(private StimulusHelper $stimulusHelper)
    {
    }

    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $attributes = $this->stimulusHelper->createStimulusAttributes();
        $attributes->addController('country-picker', ['locale' => 'fr']);
        $attributes->addTarget('country-picker', 'select');
        $attributes->addAction('country-picker', 'refresh', 'change');

        $builder->add('country', CountryType::class, [
            'attr' => $attributes->toArray(),
        ]);
    }
}
```

--------------------------------

### Chaining stimulus_controller filter

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Chains multiple controllers on the same element using the stimulus_controller filter. The rendered output combines controller names in the data-controller attribute.

```html
<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>
```

--------------------------------

### Webpack Encore webpack.config.js enableStimulusBridge

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

When using Webpack Encore, add this line to webpack.config.js to enable the Stimulus bridge.

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

--------------------------------

### stimulus_target()

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Renders a Stimulus target attribute. Can be used as a Twig function or filter. Returns an object with a toArray() method.

```APIDOC
## stimulus_target()

### Description
Renders a Stimulus target attribute. Can be used as a Twig function or filter. Returns an object with a `toArray()` method for retrieving attributes as an array.

### Method
Twig Function/Filter

### Usage
- `stimulus_target(controller, target)`
- `stimulus_target(controller, target)|stimulus_target(otherController, otherTarget)`

### Parameters
- **controller** (string) - Required - The Stimulus controller identifier.
- **target** (string) - Required - The target name or space-separated list of target names.

### Examples
```twig
<div {{ stimulus_target('controller', 'myTarget') }}>Hello</div>
<div {{ stimulus_target('controller', 'myTarget secondTarget') }}>Hello</div>
```

### Rendered Output
```html
<div data-controller-target="myTarget">Hello</div>
<div data-controller-target="myTarget secondTarget">Hello</div>
```

### Chaining Example
```twig
<div {{ stimulus_target('controller', 'myTarget')|stimulus_target('other-controller', 'anotherTarget') }}>
    Hello
</div>
```

### Rendered Output
```html
<div data-controller-target="myTarget" data-other-controller-target="anotherTarget">
    Hello
</div>
```

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

--------------------------------

### stimulus_action() with toArray() for forms

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Retrieves the generated attributes as an array, useful for passing to form fields via the 'attr' option.

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

--------------------------------

### stimulus_target() with toArray() for forms

Source: https://symfony.com/bundles/StimulusBundle/current/index.html

Retrieves the generated attributes as an array, useful for passing to form fields via the 'attr' option.

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