Skip to content
Skills Library
Programming · Building & coding

stimulus-patterns

/stimulus-patterns

Builds focused, single-purpose Stimulus controllers for progressive enhancement. Use when adding JavaScript behavior, UI interactions, form enhancements, or building reusable client-side components. WHEN NOT: For Turbo Stream/Frame patterns (see turbo-patterns skill). For server-side view logic (see rules/views.md).

Licence
MIT
Last repository change
01.06.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 01.06.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Builds focused, single-purpose Stimulus controllers for progressive enhancement. Use when adding JavaScript behavior, UI interactions, form enhancements, or building reusable client-side components. WHEN NOT: For Turbo Stream/Frame patterns (see turbo-patterns skill). For server-side view logic (see rules/views.md).

Original author description

Builds focused, single-purpose Stimulus controllers for progressive enhancement. Use when adding JavaScript behavior, UI interactions, form enhancements, or building reusable client-side components. WHEN NOT: For Turbo Stream/Frame patterns (see turbo-patterns skill). For server-side view logic (see rules/views.md).

How it works

  1. Your role
  2. Core philosophy
  3. Project knowledge
  4. Controller structure
  5. Naming conventions
  6. Composition patterns
  7. Performance tips
  8. Testing
  9. Reusable controller library
  10. Boundaries
Original SKILL.md headings · 146 lines, 527 words
SKILL.md preview
---
name: stimulus-patterns
description: >-
  Builds focused, single-purpose Stimulus controllers for progressive enhancement.
  Use when adding JavaScript behavior, UI interactions, form enhancements, or
  building reusable client-side components.
  WHEN NOT: For Turbo Stream/Frame patterns (see turbo-patterns skill). For
  server-side view logic (see rules/views.md).
license: MIT
compatibility: Stimulus 3.2+, Turbo 8.0+, Importmap
---

You are an expert Stimulus architect specializing in building focused, reusable JavaScript controllers.

## Your role

- Build small, single-purpose Stimulus controllers (most under 50 lines)
- Use Stimulus for progressive enhancement, not application logic
- Favor configuration via values/classes over hardcoding
- Output: Reusable controllers that work anywhere, with any backend

## Core philosophy

**Stimulus for sprinkles, not frameworks.** Add behavior to server-rendered HTML, don't build SPAs.

### What Stimulus IS for:
- Progressive enhancement (works without JS)
- DOM manipulation (show/hide, toggle, animate)
- Form enhancements (auto-submit, validation UI)
- UI interactions (dropdowns, modals, tooltips)
- Library integration (Sortable, Trix, etc.)

### What Stimulus is NOT for:
- Business logic (belongs in models)
- Data fetching (use Turbo)
- Client-side routing (use Turbo)
- State management (server is source of truth)

### Controller size: 62% reusable/generic, 38% domain-specific. Most under 50 lines.

## Project knowledge

**Tech Stack:** Stimulus 3.2+, Turbo 8+, Importmap (no bundler)
**Location:** `app/javascript/controllers/`
**Generate:** `bin/rails generate stimulus [name]`

## Controller structure

```javascript
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["input", "output"]
  static classes = ["active", "hidden"]
  static values = {
    url: String,
    timeout: { type: Number, default: 5000 }
  }

  connect() { /* Setup */ }
  disconnect() { /* Cleanup -- always clean up! */ }

  actionMethod(event) {
    event.preventDefault()
    this.element.classList.toggle(this.activeClass)
  }

  #privateHelper() { /* Use # prefix */ }
}
```

## Naming conventions

- **HTML:** `data-controller="auto-submit"` (kebab-case)
- **Filename:** `auto_submit_controller.js` (snake_case)
- **Targets:** `data-auto-submit-target="input"` (camelCase)
- **Values:** `data-auto-submit-url-value="/path"` (camelCase)
- **Classes:** `data-auto-submit-active-class="is-active"` (camelCase)

## Composition patterns

### Multiple controllers on one element

```erb
<div data-controller="dropdown modal">
  <%# Both controllers active %>
</div>
```

### Nested controllers

```erb
<div data-controller="sortable">
  <div data-controller="card">
    <div data-controller="dropdown">
      <%# Three controllers in hierarchy %>
    </div>
  </div>
</div>
```

### Controller communication via events

```javascript
// Publisher dispatches
this.dispatch("published", { detail: { content: "data" } })

// Subscriber listens via data-action
// data-action="publisher:published->subscriber#handleEvent"
```

## Performance tips

1. **Event delegation:** One listener on parent, not many on children
2. **Debounce expensive ops:** Use `setTimeout` with clear pattern
3. **Always clean up in disconnect():** Clear timeouts, observers, listeners
4. **Use IntersectionObserver:** For visibility-based behavior

```javascript
disconnect() {
  clearTimeout(this.timeout)
  this.observer?.disconnect()
  document.removeEventListener("click", this.boundClose)
}
```

## Testing

```ruby
# System tests are the primary way to test Stimulus controllers
test "toggle card details" do
  visit card_path(cards(:logo))
  assert_no_selector ".card__details"
  click_button "Show Details"
  assert_selector ".card__details"
end
```

## Reusable controller library

**UI:** toggle, dropdown, modal, tabs, tooltip
**Forms:** auto-submit, character-counter, form-validation, password-visibility
**Utility:** clipboard, auto-dismiss, confirm, disable
**Integration:** sortable, trix, flatpickr
**Tracking:** beacon, visibility, scroll

## Boundaries

- **Always:** Keep controllers under 50 lines, single responsibility, use values/classes for config, clean up in disconnect(), use `#` private methods, provide no-JS fallback
- **Ask first:** Before adding business logic, before fetching data (use Turbo), before managing complex state, before creating domain-specific controllers (favor generic + composition)
- **Never:** Build SPAs, put business logic in controllers, manage app state client-side, skip disconnect() cleanup, hardcode values, create god controllers, forget CSRF tokens in fetch

## Reference files

- `references/controller-catalog.md` -- Common controller patterns (toggle, modal, dropdown, form enhancement)
- `references/stimulus-examples.md` -- Full controller implementations with HTML integration
Files in this package (3)
  • SKILL.md 5 KB
  • references/controller-catalog.md 6 KB
  • references/stimulus-examples.md 8 KB

Versions

RepositoryScoreLicence
This page · ThibautBaissac/rails_ai_agents100MIT
davidteren/hotwire-codex-skills100MIT

Database snapshot: 13.11.2026 · package version 4df60c7b3e37 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100turbo-patterns
    Creates Turbo Streams, Turbo Frames, and morphing patterns for real-time UI updates. Use when adding real-time updates, partial page rendering, form submissions, or broadcasting. WHEN NOT: For Stimulus JavaScript controllers (see stimulus-patterns skill). For general view…
  • 100rails-cto-stimulus
    How to write Stimulus controllers for this Rails 8 / Hotwire project. Use when creating, modifying, or debugging Stimulus controllers, wiring controllers to ERB views, or integrating JavaScript behavior with Turbo Streams and Frames. Also use when the user mentions "stimulus",…
  • 95rails-viewcomponents
    Specialized skill for building ViewComponents with Hotwire (Turbo & Stimulus). Use when creating reusable UI components, implementing frontend interactions, building Turbo Frames/Streams, or writing Stimulus controllers. Includes component testing with Lookbook.
  • 100better-stimulus
    Apply opinionated StimulusJS best practices from betterstimulus.com. Use this skill whenever writing, reviewing, debugging, or refactoring Stimulus controllers. Triggers when user asks to write, fix, or review a Stimulus controller, asks about data-controller, data-action,…
  • 100rails-hotwire
    Ruby on Rails Hotwire best practices for building interactive applications with Turbo Drive, Turbo Frames, Turbo Streams, Turbo 8 morphing, and Stimulus controllers. This skill should be used when writing, reviewing, or refactoring Hotwire-powered Rails code to ensure optimal…
  • 100rails-design-system
    Ruby on Rails design system guidelines for building consistent, maintainable UI with minimal abstraction. This skill should be used when creating or refactoring Rails views, partials, components, form builders, helpers, Stimulus controllers, Turbo Frames, Turbo Streams, or…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.