Skip to content

smnandre/symfony-ux-skills / skills/stimulus

stimulus

Verified

Stimulus JS framework for Symfony UX -- client-side behavior via HTML data attributes, zero server round-trips. Use when creating controllers for DOM manipulation, handling click/input/submit events, managing targets and values, wiring outlets between controllers, wrapping third-party JS libraries, or building toggles, dropdowns, modals, tabs, clipboard interactions. Code triggers: data-controller, data-action, data-target, data-*-value, data-*-class, data-*-outlet, stimulusFetch lazy, connect(), disconnect(), static targets, static values. Also trigger when the user asks "how do I add a click handler", "how to toggle a class", "how to build a dropdown/modal/tabs", "how to wrap a JS library in Symfony", "add keyboard shortcuts", "lazy-load a controller", "listen to global events", "communicate between controllers". Do NOT trigger for partial page updates without JS (use turbo), server-rendered reactivity (use live-component), or reusable Twig templates (use twig-component).

FileKindSize
SKILL.mdskill md8.1 KB
references/api.mdmarkdown9.8 KB
references/gotchas.mdmarkdown8.7 KB
references/patterns.mdmarkdown12.0 KB

references/gotchas.md

View on GitHub
# Stimulus Gotchas & Debugging

Common mistakes, pitfalls, and debugging strategies.

---

## Naming Mistakes

### Controller Name Mismatch

```javascript
// File: assets/controllers/userProfile_controller.js  ❌ Wrong
// File: assets/controllers/user_profile_controller.js ✅ Correct
```

```html
<!-- data-controller must match file name (underscores become dashes) -->
<div data-controller="userProfile">  ❌ Wrong
<div data-controller="user-profile"> ✅ Correct
```

### Target Name Case

```javascript
static targets = ['errorMessage']  // camelCase in JS
```

```html
<!-- camelCase preserved in HTML -->
<span data-search-target="errorMessage">   ✅ Correct
<span data-search-target="error-message">  ❌ Wrong
```

### Value Name Case

```javascript
static values = { apiUrl: String }  // camelCase in JS
```

```html
<!-- kebab-case in HTML -->
<div data-search-api-url-value="/api">  ✅ Correct
<div data-search-apiUrl-value="/api">   ❌ Wrong
```

---

## Scope Issues

### Target Outside Controller Scope

```html
<div data-controller="tabs">
    <button data-tabs-target="tab">Tab 1</button>  ✅ Inside scope
</div>
<div data-tabs-target="panel">Content</div>  ❌ Outside scope - won't work
```

### Nested Controller Confusion

```html
<div data-controller="parent">
    <div data-controller="child">
        <span data-parent-target="item">  ❌ Child blocks parent's access
        <span data-child-target="item">   ✅ Correct scope
    </div>
</div>
```

Parent cannot see targets inside nested child controller scope.

---

## Lifecycle Timing

### Accessing Targets Too Early

```javascript
export default class extends Controller {
    static targets = ['output'];

    initialize() {
        this.outputTarget.textContent = 'Hello';  ❌ Targets not ready
    }

    connect() {
        this.outputTarget.textContent = 'Hello';  ✅ Targets available
    }
}
```

### Not Cleaning Up

```javascript
export default class extends Controller {
    connect() {
        this.interval = setInterval(() => this.tick(), 1000);
        window.addEventListener('resize', this.handleResize);  ❌ Leaks
    }

    // Missing disconnect() - causes memory leaks with Turbo!

    disconnect() {
        clearInterval(this.interval);
        window.removeEventListener('resize', this.handleResize);  ✅
    }
}
```

### Binding `this` for Event Listeners

```javascript
export default class extends Controller {
    connect() {
        // ❌ Wrong - `this` will be wrong when called
        window.addEventListener('resize', this.handleResize);
        
        // ✅ Correct - bind or use arrow function
        this.boundResize = this.handleResize.bind(this);
        window.addEventListener('resize', this.boundResize);
    }

    disconnect() {
        window.removeEventListener('resize', this.boundResize);
    }
}
```

---

## Value Gotchas

### Values Are Strings in HTML

```html
<div data-counter-count-value="5">  <!-- "5" is a string -->
```

Stimulus converts based on type declaration:

```javascript
static values = { 
    count: Number,  // Converted to number
    enabled: Boolean  // "true"/"false" converted to boolean
}
```

### Boolean Values

```html
<div data-toggle-enabled-value="true">   ✅ Works
<div data-toggle-enabled-value="false">  ✅ Works
<div data-toggle-enabled-value="">       ❌ Empty string, not false
<div>                                    <!-- Missing = uses default -->
```

### Array/Object Values Need Valid JSON

```html
<div data-chart-data-value='[1,2,3]'>           ✅ Valid JSON
<div data-chart-data-value="[1,2,3]">           ✅ Also works
<div data-chart-data-value='{"a": 1}'>          ✅ Valid JSON
<div data-chart-data-value='{a: 1}'>            ❌ Invalid JSON
<div data-chart-data-value="{{ data }}">        ❌ May produce invalid JSON
<div data-chart-data-value="{{ data|json_encode|e('html_attr') }}">  ✅ Twig
```

### Value Changed Fires on Connect

```javascript
countValueChanged(value, previousValue) {
    // On connect: previousValue is undefined
    if (previousValue === undefined) return;  // Skip initial call if needed
}
```

---

## Action Gotchas

### Forgetting Event Parameter

```javascript
// ❌ Can't access event
submit() {
    // event is undefined
}

// ✅ Correct
submit(event) {
    event.preventDefault();
}
```

### Action Parameters Are Always Strings

```html
<button data-item-id-param="123" data-item-active-param="true">
```

```javascript
delete(event) {
    event.params.id;      // "123" (string, not number)
    event.params.active;  // "true" (string, not boolean)
    
    // Convert manually if needed
    const id = parseInt(event.params.id, 10);
    const active = event.params.active === 'true';
}
```

### Default Events Don't Work Everywhere

```html
<!-- ❌ div has no default event -->
<div data-action="myController#click">

<!-- ✅ Specify event explicitly -->
<div data-action="click->myController#click">
```

---

## Turbo Compatibility

### Controller Connects Multiple Times

With Turbo Drive, controllers may connect/disconnect as you navigate:

```javascript
export default class extends Controller {
    connect() {
        // This may run multiple times during navigation
        // Don't assume it only runs once
        console.log('Connected');
    }
}
```

### Lazy Controllers + Turbo Issue

Known issue: lazy controllers may not load when navigating with Turbo if the controller wasn't on the first page visited.

Workarounds:
1. Use eager loading for critical controllers
2. Add `data-turbo-track="reload"` to force page reload
3. Ensure controller is referenced on initial page

### Morphing and Targets

When using Turbo morphing, targets may be replaced. Use `[target]TargetConnected` callbacks:

```javascript
static targets = ['item']

itemTargetConnected(element) {
    // Reinitialize any third-party libraries on this element
    this.initializeElement(element);
}
```

---

## Debugging Tips

### Enable Debug Mode

```javascript
// assets/bootstrap.js
import { Application } from '@hotwired/stimulus';

const app = Application.start();
app.debug = true;  // Logs lifecycle events to console
```

### Check Controller Registration

```javascript
// In browser console -- enables lifecycle logging
Stimulus.debug = true;
```

### Verify Controller is Connected

```javascript
connect() {
    console.log(`${this.identifier} connected to`, this.element);
}
```

### Check Targets Exist

```javascript
someMethod() {
    console.log('Has target?', this.hasOutputTarget);
    console.log('Targets:', this.outputTargets);
}
```

### Inspect Element Data

```javascript
connect() {
    console.log('Values:', {
        url: this.urlValue,
        count: this.countValue,
    });
    console.log('Element dataset:', this.element.dataset);
}
```

### Common Console Errors

| Error | Cause |
|-------|-------|
| `Cannot read property 'xyz' of undefined` | Target doesn't exist or is out of scope |
| `this.xyzTarget is not a function` | Typo in target name or not declared in `static targets` |
| `Controller not found: xyz` | File naming mismatch or controller not registered |

---

## Performance Tips

### Use Lazy Loading for Heavy Controllers

```javascript
/* stimulusFetch: 'lazy' */
import { Controller } from '@hotwired/stimulus';
import HeavyLibrary from 'heavy-library';  // Only loaded when needed
```

### Debounce Expensive Operations

```javascript
connect() {
    this.debouncedSearch = this.debounce(this.search.bind(this), 300);
}

debounce(fn, wait) {
    let timeout;
    return (...args) => {
        clearTimeout(timeout);
        timeout = setTimeout(() => fn(...args), wait);
    };
}
```

### Use `disconnect()` to Clean Up

Always remove event listeners, clear intervals, abort fetches:

```javascript
connect() {
    this.abortController = new AbortController();
    fetch(url, { signal: this.abortController.signal });
}

disconnect() {
    this.abortController.abort();
}
```

### Avoid Querying DOM in Loops

```javascript
// ❌ Slow
items.forEach(item => {
    document.querySelector(`[data-id="${item.id}"]`).classList.add('active');
});

// ✅ Better - use targets
this.itemTargets.forEach(target => {
    target.classList.add('active');
});
```

---

## Third-Party Libraries

### Initializing Libraries on Connect

```javascript
import Choices from 'choices.js';

export default class extends Controller {
    connect() {
        this.choices = new Choices(this.element);
    }

    disconnect() {
        this.choices.destroy();  // Clean up!
    }
}
```

### Re-initializing After Turbo Navigation

```javascript
static targets = ['select']

selectTargetConnected(element) {
    // Called when target added to DOM (including after Turbo morphing)
    element._choices = new Choices(element);
}

selectTargetDisconnected(element) {
    element._choices?.destroy();
}
```
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall