Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/client-passive-event-listeners.md
Open on GitHub

What 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 useEffect hooks

Example prompts for the agent

  • Review the touch listeners in this component and make them passive to fix scroll lag
  • Add telemetry listeners for touchstart and wheel without 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.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set130

The whole set →
server-cache-lru The server-cache-lru rule explains when React.cache() is too narrow and an LRU cache should share data between requests. Use it for sequential actions that reuse the same records. CX Codex +1 ★ 7,191repo stars advanced-event-handler-refs advanced-event-handler-refs guides Claude Code to keep event callbacks in refs or useEffectEvent, stopping React effects from re-subscribing on every render. CX Codex +1 ★ 7,191repo stars server-parallel-fetching The server-parallel-fetching rule shows how to compose React Server Components so independent data requests can run in parallel. Use it when one component waits on another component’s fetch. CX Codex +1 ★ 7,191repo stars _sections Defines eight performance optimization sections, ranks them by impact, and guides the agent in prioritizing code improvements. Install once, reference by ID when analyzing bottlenecks. CX Codex +1 ★ 7,191repo stars js-cache-storage js-cache-storage keeps localStorage, sessionStorage and cookie values in memory so reads stop hitting synchronous browser storage. CX Codex +1 ★ 7,191repo stars rerender-use-ref-transient-values The rerender-use-ref-transient-values rule teaches the agent to store frequently changing values in useRef instead of useState to avoid re-rendering the component on every update. CX Codex +1 ★ 7,191repo stars js-length-check-first js-length-check-first — a rule for Claude Code that prompts the AI to check array lengths before running expensive operations like sorting or deep equality checks. If lengths differ, arrays cannot be equal—no expensive work needed. CX Codex +1 ★ 7,191repo stars js-tosorted-immutable The js-tosorted-immutable rule replaces mutating .sort() with .toSorted(), keeping React props and state arrays unchanged during sorting. CX Codex +1 ★ 7,191repo stars

Project sponsors

Companies that keep this analytics open