Skip to content

thedaviddias/Front-End-Checklist / skills/scrolljacking

scrolljacking

Verified

Use when reviewing rendered HTML, interactive components, or design-system patterns related to Avoid scrolljacking and custom scroll behavior. Check native semantics first, then inspect keyboard behavior, focus flow, accessible names, and screen-reader output where relevant.

FileKindSize
SKILL.mdskill md2.1 KB
references/rule.mdmarkdown5.1 KB

references/rule.md

View on GitHub
# Avoid scrolljacking and custom scroll behavior

> Natural scroll behavior is preserved without custom scroll speeds, directions, or hijacked scroll events.

**Priority:** medium · **Difficulty:** beginner · **Time:** 15 min

---
Scrolljacking breaks user trust by making the page behave unpredictably.

## Code Example

```javascript
// ❌ Bad: Hijacking scroll for section navigation
window.addEventListener('wheel', (e) => {
  e.preventDefault() // Blocks native scroll
  const direction = e.deltaY > 0 ? 'down' : 'up'
  scrollToNextSection(direction)
})

// ❌ Bad: Modifying scroll speed
window.addEventListener('scroll', (e) => {
  window.scrollTo(0, window.scrollY * 0.5) // Half-speed scroll
})

// ❌ Bad: Horizontal scroll from vertical input
container.addEventListener('wheel', (e) => {
  e.preventDefault()
  container.scrollLeft += e.deltaY // Confusing!
})
```

## Why It Matters

Scrolljacking breaks user expectations, interferes with assistive technologies, and creates unpredictable experiences that frustrate users with motor impairments or cognitive disabilities.

## What Is Scrolljacking?

| Type | Problem |
|------|---------|
| Modified scroll speed | Scroll wheel moves more/less than expected |
| Scroll direction change | Horizontal scroll on vertical input |
| Snap-to-section | Each scroll jump to next "page" |
| Scroll-triggered animations | Animation blocks continued scrolling |
| Infinite scroll without fallback | No way to reach footer content |

## Acceptable Scroll Behaviors

```css
/* ✅ OK: CSS scroll snap (user stays in control) */
.container {
  scroll-snap-type: y mandatory;
  overflow-y: scroll;
}

.section {
  scroll-snap-align: start;
}

/* User can still scroll freely, snap is just a guide */
```

```javascript
// ✅ OK: Scroll-triggered animations that don't block
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      entry.target.classList.add('animate-in')
    }
  })
}, { threshold: 0.1 })

// Animation happens, but scrolling continues normally
document.querySelectorAll('.animate-on-scroll').forEach(el => {
  observer.observe(el)
})
```

## Detecting Scrolljacking

```javascript
// Console test: check if scrolling is hijacked
function detectScrolljacking() {
  let scrollEvents = 0
  let scrollBlocked = false

  const handler = (e) => {
    scrollEvents++
    if (e.defaultPrevented) {
      scrollBlocked = true
      console.warn('Scroll event was prevented!')
    }
  }

  window.addEventListener('wheel', handler, { passive: false })

  setTimeout(() => {
    window.removeEventListener('wheel', handler)
    console.log(`Scroll events: ${scrollEvents}, Blocked: ${scrollBlocked}`)
  }, 5000)
}

detectScrolljacking()
```

## If Custom Scroll Is Required

```tsx
function ScrollEffects({ children }: { children: React.ReactNode }) {
  const [effectsEnabled, setEffectsEnabled] = useState(true)
  const prefersReducedMotion = useReducedMotion()

  // Disable by default if user prefers reduced motion
  useEffect(() => {
    if (prefersReducedMotion) {
      setEffectsEnabled(false)
    }
  }, [prefersReducedMotion])

  return (
    <div className={effectsEnabled ? 'scroll-effects-on' : ''}>
      <div className="scroll-toggle" role="region" aria-label="Scroll preferences">
        <label>
          <input
            type="checkbox"
            checked={effectsEnabled}
            onChange={(e) => setEffectsEnabled(e.target.checked)}
          />
          Enable scroll animations
        </label>
      </div>
      {children}
    </div>
  )
}
```

## Infinite Scroll Accessibility

```tsx
// ❌ Bad: No way to reach footer
function InfiniteList() {
  return (
    <div onScroll={loadMore}>
      {items.map(item => )}
      {/* Footer is unreachable! */}
    </div>
  )
}

// ✅ Good: Pagination fallback
function AccessibleInfiniteList() {
  return (
    <div>
      {items.map(item => )}

      <button onClick={loadMore} aria-label="Load more items">
        Load more
      </button>

      <nav aria-label="Pagination">
        <a href="?page=1">Page 1</a>
        <a href="?page=2">Page 2</a>
        {/* Footer always reachable via pagination */}
      </nav>

      <footer>Contact info, links, etc.</footer>
    </div>
  )
}
```

## Exceptions

- Evaluate the rendered experience before treating a static-code smell as a blocker; interaction timing, browser behavior, and assistive technology output often determine severity.
- Not every secondary accessibility issue deserves equal weight; prioritize the issue that most directly blocks perception, operation, or understanding.
- Avoid adding redundant markup or ARIA solely to satisfy a rule when a simpler semantic implementation would eliminate the issue entirely.

## Verification

### Automated Checks

- Use browser accessibility tooling, axe, Lighthouse, or equivalent automated checks against a representative rendered state.

### Manual Checks

- Scroll with mouse wheel—movement should feel natural
- Use keyboard Page Up/Down—should move predictable amounts
- Test with trackpad, touchscreen, and scroll wheel
- Verify assistive technology scroll commands work
- Confirm all page content (including footer) is reachable
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