locomotive-scroll
Scroll suave y parallax con Locomotive Scroll: data-scroll-*, sticky, scroll horizontal, eventos scroll/call, sync con GSAP ScrollTrigger (scrollerProxy). No para reveals simples (scroll-reveal-librar
SKILL.mdcore/skills-overlay/locomotive-scroll/SKILL.md
GitHublocomotive-scroll (índice Senzu, ES)
Documentación completa upstream (inglés): SKILL.upstream.md (480 líneas). No la leas entera: usa el mapa y lee solo la sección que necesites (Read con offset/limit o Grep).
Cuándo usar / cuándo NO
- Usar: landings inmersivas tipo Apple con scroll suavizado (lerp), capas parallax por velocidad y elementos sticky dentro de secciones.
- Usar: scroll horizontal o storytelling largo que necesita progreso por elemento (
data-scroll-id) o disparadoresdata-scroll-call. - NO usar: solo fade-in al entrar en viewport → scroll-reveal-libraries (AOS) o IntersectionObserver.
- NO usar: animaciones scrubbed/pin sin smooth scroll → gsap-scrolltrigger (ScrollSmoother si se quiere suavizado); en React → motion-framer.
Lectura mínima por tarea
| Tarea | Lee solo |
|---|---|
| Empezar un proyecto/starter | SKILL.upstream.md L33-116 (§Installation + §Core Concepts) + assets/starter_locomotive/ |
| Parallax, sticky, scroll horizontal | L139-161 (§2. Parallax), L193-209 (§4. Sticky), L236-254 (§6. Horizontal) |
| Eventos, progreso y scrollTo | L163-191 (§3. Viewport Detection) + L211-234 (§5. Programmatic Scrolling) + L333-353 (§Instance Methods) |
| Combinar con GSAP ScrollTrigger | L277-331 (§Integration with GSAP ScrollTrigger) + references/gsap_integration.md |
| Depurar / rendimiento | L355-383 (§Performance Optimization) + L385-466 (§Common Pitfalls) |
Mapa de SKILL.upstream.md
| Líneas | Sección | Para qué |
|---|---|---|
| 10-32 | Overview | Capacidades y trade-offs (accesibilidad, móviles, position fixed) |
| 33-47 | Installation | npm + CSS obligatorio, o CDN |
| 49-116 | Core Concepts | Estructura data-scroll-container/-section, opciones de new LocomotiveScroll, tabla de atributos |
| 118-275 | Common Patterns | Smooth básico, parallax, eventos, sticky, scrollTo, horizontal, breakpoints tablet/smartphone |
| 277-331 | Integration with GSAP ScrollTrigger | scrollerProxy, scroller, refresh/update mutuos |
| 333-353 | Instance Methods | init/update/destroy/start/stop, scrollTo, on/off |
| 355-383 | Performance Optimization | Secciones, limitar parallax, desactivar en móvil, update en resize, destroy |
| 385-466 | Common Pitfalls | Fixed roto, lazy images, posiciones desactualizadas, accesibilidad, fugas de memoria, z-index |
| 468-480 | Related Skills / Resources | Skills relacionadas e índice de scripts, references y assets |
Recursos
references/api_reference.md— API completa: opciones, atributos, métodos, eventos.references/gsap_integration.md— Patrones de ScrollTrigger + Locomotive (scrollerProxy, pin, scrub).scripts/generate_config.py— Genera la configuración inicial:py -3 scripts/generate_config.py --smooth/--horizontal(opython3 …).scripts/integration_helper.py— Genera código de integración GSAP por patrón/framework:py -3 scripts/integration_helper.py --pattern fade-in --framework react.assets/starter_locomotive/— Starter completo (index.html, main.js, style.css, package.json, README.md).
Reglas duras
- Importa siempre
locomotive-scroll/dist/locomotive-scroll.css; envuelve el contenido endata-scroll-containery segmenta condata-scroll-section. - Respeta
prefers-reduced-motion:smooth: !matchMedia('(prefers-reduced-motion: reduce)').matches; considerasmartphone: { smooth: false }. - Llama a
scroll.update()tras insertar contenido dinámico, cargar imágenes o en resize; llama ascroll.destroy()al desmontar o cambiar de ruta. - Los elementos
position: fixedvan fuera del contenedor (o usadata-scroll-sticky); las capas parallax necesitan z-index explícito. - Con GSAP: registra
scrollerProxy, pasascroller: '[data-scroll-container]'a cada ScrollTrigger y encadenaScrollTrigger.refresh()→locoScroll.update(). - SSR-safe: instancia solo en cliente (
useEffect/onMounted/client:only), nunca en el nivel superior del módulo.
Integración con el stack del proyecto
- Detecta el stack como indica la skill
front-activation/skill-router(senzu/senzu.json → package.json). Es vanilla JS y sirve en HTML estático, Astro, Vue (instancia enonMounted, destruye enonUnmounted) y React (useEffectcon cleanup). En proyectos React con GSAP, valora ScrollSmoother (gsap-scrolltrigger) para evitar dos sistemas de scroll; con barba-js, destruye y recrea la instancia en cada transición.