client-passive-event-listeners — Claude Code rule
client-passive-event-listeners instructs the agent to add { passive: true } to touch and wheel listeners, preventing scroll stutter in browser viewports.
MIT ★ 7,191 updated 2026-10-24
.claude/rules/client-passive-event-listeners.mdWhat client-passive-event-listeners does
The rule instructs the coding assistant to supply { passive: true } when attaching listeners to wheel and touchstart events. By default, browsers pause scrolling until the handler finishes to check for a potential preventDefault() invocation. This creates noticeable scroll lag.
The guidance establishes clear boundaries. Passive listeners are required for telemetry, logging, and metrics where default browser actions remain untouched. When building custom gestures or custom zoom controls that explicitly invoke preventDefault(), passive listeners break functionality and must be avoided.
What it helps with
- eliminate scroll stutter caused by synchronous touch and wheel event listeners
- apply
{ passive: true }to telemetry, tracking, and metric handlers - distinguish custom swipe or zoom handlers from read-only touch interactions
- optimize touch and scroll performance inside React
useEffecthooks
Example prompts for the agent
- Review the touch listeners in this component and make them passive to fix scroll lag
- Add telemetry listeners for
touchstartandwheelwithout blocking native browser scrolling - Refactor our global wheel event subscription using
{ passive: true }
How to install client-passive-event-listeners
Manually: put the files in place
.claude/rules/client-passive-event-listeners.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/client-passive-event-listeners.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/client-passive-event-listeners.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/client-passive-event-listeners.mdManually: put the files in place
.clinerules/client-passive-event-listeners.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about client-passive-event-listeners
How to install client-passive-event-listeners in Claude Code?
Save the rule file to .claude/rules/client-passive-event-listeners.md in your project repository.
What does client-passive-event-listeners do?
It instructs the AI assistant to append { passive: true } to touch and wheel event handlers, eliminating scroll delay.
When should passive event listeners be avoided?
Do not use passive listeners if your handler calls preventDefault(), such as in custom swipe gestures or custom zoom handlers.
Source text
client-passive-event-listeners.md · MIT
---
title: Use Passive Event Listeners for Scrolling Performance
impact: MEDIUM
impactDescription: eliminates scroll delay caused by event listeners
tags: client, event-listeners, scrolling, performance, touch, wheel
---
## Use Passive Event Listeners for Scrolling Performance
Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
**Incorrect:**
```typescript
useEffect(() => {
const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
document.addEventListener('touchstart', handleTouch)
document.addEventListener('wheel', handleWheel)
return () => {
document.removeEventListener('touchstart', handleTouch)
document.removeEventListener('wheel', handleWheel)
}
}, [])
```
**Correct:**
```typescript
useEffect(() => {
const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
document.addEventListener('touchstart', handleTouch, { passive: true })
document.addEventListener('wheel', handleWheel, { passive: true })
return () => {
document.removeEventListener('touchstart', handleTouch)
document.removeEventListener('wheel', handleWheel)
}
}, [])
```
**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
© tech-leads-club · MIT · tech-leads-club/agent-skills