Scrolly: A Complete Guide to Scroll-Driven Web Animations

What Is Scrolly?

Scrolly is a lightweight, zero-dependency JavaScript library that brings your website to life through scroll-driven animations. Unlike complex animation frameworks that require significant overhead, scrolly provides an elegant, declarative approach using simple HTML data attributes. When users scroll through your content, elements can fade, slide, bounce, or transform into view--creating an engaging storytelling experience that guides attention without interrupting the natural browsing flow.

The philosophy behind scrolly centers on user-centered design principles. Rather than forcing users to interact with static content, scroll-driven animations respond to their natural behavior, revealing information progressively as they explore the page. This approach reduces cognitive load, increases time on page, and creates memorable experiences that distinguish your brand from competitors relying on static layouts.

Scrollytelling emerged from data journalism and interactive storytelling, with publications like The New York Times and The Guardian pioneering techniques that reveal content progressively as readers scroll. The Pudding, a digital publication known for data-driven stories, documented their exploration of scrollytelling libraries and found that the technique significantly increases reader engagement when implemented thoughtfully. Modern scrolly libraries like scrolly.js built upon these lessons, creating tools that balance power with simplicity.

This guide covers everything from basic implementation to advanced techniques, providing you with the knowledge to create sophisticated scroll-driven experiences that convert visitors into engaged users.

window.scrolly Fundamentals

Installation and Basic Setup

Getting started with scrolly requires including the library in your project and initializing it when the page loads. The library consists of two files you need: the core scrolly.js script and the cssanimation.css stylesheet that provides the animation classes. The initialization call activates all data-scrolly attributes throughout your page. Once initialized, the library automatically watches for scroll events and triggers animations when elements enter or exit the viewport according to your specifications.

This one-time setup eliminates the need for repetitive code throughout your project. For modern build systems, you can import scrolly as an ES module or include it via package managers. The zero-dependency design means you don't need to worry about bundling additional libraries or managing complex dependency chains.

The Animation System

Scrolly separates the detection logic from the animation effects, using a two-part system. The library handles viewport detection and triggers events, while a separate animation library provides the actual visual effects. This separation of concerns means you can swap out animation libraries or create custom effects while still benefiting from scrolly's scroll detection.

The animation classes follow a consistent naming convention that makes them easy to discover and apply. Classes like fadeIn, moveFromRight, bounceInTop, and flipX describe the effect they produce. When you apply these classes through scrolly's data attributes, the library adds and removes them based on scroll position, creating dynamic visual feedback.

Configuration Options

While scrolly works immediately with sensible defaults, the library provides configuration options that control global behavior. These settings affect how the library detects scroll position and determines when animations should trigger.

scrollyOffsetTop sets the default distance between an element and the top of the browser window before top-triggered animations activate. The default value of 0px means animations trigger as soon as any part of the element enters the viewport. Increasing this value causes animations to wait until elements scroll further down before triggering.

scrollyOffsetBottom works similarly for bottom-triggered animations, defining the distance from the bottom of the browser window. This proves particularly useful when you want animations to trigger only after users have scrolled past a certain point, creating a sense of progression through longer content.

These global settings provide a baseline that individual elements can override using their own data attributes, giving you fine-grained control where needed while maintaining efficiency through sensible defaults.

Platform-Specific Offsets

Scrolly includes device and operating system detection that allows different offset values for different platforms. These platform-specific settings compensate for different browser behaviors, touch interfaces, and screen sizes. Mobile devices often need larger offsets because users scroll faster and touch targets differ from mouse-controlled desktops.

Data Attribute Reference

Scrolly's power lies in its declarative data attribute system. Rather than writing complex JavaScript event handlers, you simply add attributes to your HTML elements that describe what animation should occur and when. The library handles all the scroll detection logic behind the scenes, activating your specified animations when elements enter or exit the viewport.

Core Scroll Triggers

The primary scroll-triggered attributes are data-scrolly-top and data-scrolly-bottom. These control animations when elements enter the viewport from below or above, respectively. By combining both attributes, you create bidirectional animations that respond regardless of scroll direction, creating consistent visual feedback that works with natural browsing behavior.

Character Animation

One of scrolly's distinctive features is the ability to animate individual characters within text elements through the data-scrolly-characters attribute. This creates eye-catching headlines where characters animate in sequence or randomly, drawing attention to important messages. The character animation works by wrapping each character in a span element and applying animations to those spans individually.

Element-Specific Controls

Individual elements can override global offset settings using data-scrolly-offset-top and data-scrolly-offset-bottom. These attributes prove essential when you have elements of varying sizes or positions that need different trigger points, enabling precise choreography of multiple animated elements throughout your page.

data-scrolly-top

The data-scrolly-top attribute defines animations that trigger when elements scroll into view from below--that is, as the user scrolls upward or as content enters the viewport from the bottom edge. This attribute creates the most common animation pattern where elements reveal themselves as users explore the page, creating a natural, responsive feel where elements acknowledge the user's exploration.

When an element with this attribute scrolls upward past the viewport threshold, the specified animation plays. If the user scrolls back down and the element exits the viewport, the animation reverses or resets depending on your configuration. You can chain multiple animation parameters within the same attribute, separated by commas, to customize duration, delay, and timing function for each element.

data-scrolly-bottom

The data-scrolly-bottom attribute triggers animations when users scroll downward and content approaches from above. This pattern works well for elements that should appear as if they're sliding into place as the user progresses through the content, creating a sense of forward momentum and progression.

Using both attributes together creates bidirectional animations that respond regardless of scroll direction, ensuring your animations feel natural whether users are scrolling up to review content or continuing downward to explore more of your page. This flexibility allows you to create consistent visual feedback that works with natural browsing behavior rather than forcing users to scroll in a particular direction to see animations.

data-scrolly-characters

Create eye-catching headlines by animating individual characters. The sequentially parameter animates characters one after another in order, creating a dramatic reveal effect that builds anticipation. The randomly parameter creates a more dynamic, attention-grabbing effect where characters animate in a chaotic but controlled pattern.

Character animation works by wrapping each character in a span element and applying animations to those spans individually. This creates opportunities for dramatic headlines that draw attention and communicate importance through visual emphasis. When combined with scroll triggers, character animations create memorable moments as users arrive at key sections of your content.

Animation Parameters and Timing

Scrolly provides extensive control over how animations behave through a system of parameters that modify the core animation effects. Understanding these parameters allows you to create polished, professional animations that feel natural rather than mechanical. The parameters work together to give you fine-grained control over duration, timing, repetition, and direction.

By default, animations play once with a one-second duration, but these values can be customized for each element. The parameter system uses a simple key-value syntax within the animation specification, allowing you to combine multiple parameters in a single attribute. This approach keeps your HTML clean while providing powerful animation control.

The key parameters include duration for controlling animation speed, delay for staggered effects, timing functions for natural motion curves, iteration count for repeating animations, and direction for controlling playback direction. Each parameter can be combined with others to create complex animation behaviors that serve your specific design goals.

Duration

Animation duration determines how long an animation takes to complete, and scrolly allows you to specify this for each element. The default duration of one second works for most cases, but adjusting this parameter creates different emotional effects that can dramatically impact user perception.

Longer durations (2-3 seconds) create a sense of elegance and sophistication, making animations feel smooth and polished. They're well-suited for subtle effects like fades and subtle movements. Shorter durations (200-500 milliseconds) feel snappy and responsive, creating energy and immediacy. They're better suited for dramatic effects like bounces and quick reveals. Matching duration to the animation type helps maintain visual coherence--subtle fades can take longer, while dramatic bounces should be quick to avoid feeling sluggish.

Delay and Timing Functions

The delay parameter specifies how long to wait before starting an animation, measured in seconds or milliseconds. Delays prove essential when animating multiple elements in sequence, allowing you to stagger effects for a polished, professional appearance. By carefully choosing delay values, you can create cascading animations that guide users through your content.

Timing functions control the acceleration curve of animations, making them feel natural rather than mechanical. The standard CSS timing functions work within scrolly's parameter system. Ease-out creates fast starts with gradual slowdowns, ideal for elements entering the viewport. Linear provides constant speed throughout, which works well for continuous motion effects. Custom cubic-bezier curves allow you to create unique motion characteristics that match your brand personality.

Interaction Events

Beyond scroll-based triggers, scrolly supports user interaction events that respond to deliberate user actions. These events create interactive components where animations provide feedback and guidance, making your interface feel responsive and alive. Interaction animations serve a purpose beyond decoration--they confirm user actions, highlight interactive elements, and guide attention to important content.

The supported interaction events include click triggers for button-like behaviors, mouseover for hover states, and mouseout for exit animations. Each event can be combined with scroll triggers or used independently, giving you flexibility in designing interactive experiences. The dual-trigger capability enables sophisticated interactive components like collapsible panels, reveal-on-click content, and guided tours.

These interaction patterns work particularly well for card components, button states, interactive diagrams, and navigation elements. By providing visual feedback on user actions, you create interfaces that feel intuitive and responsive, reducing friction and improving the overall user experience.

Click and Hover Animations

Beyond scroll triggers, scrolly supports user interaction events including click, mouseover, and mouseout for interactive components. The click trigger works independently of scroll triggers, meaning elements can animate both when scrolled into view and when clicked. This dual-trigger capability enables sophisticated interactive components like collapsible panels, reveal-on-click content, and feedback indicators.

Hover effects add another dimension of interactivity, working well for card components that highlight on hover, button states that provide feedback, interactive diagrams that reveal information, and navigation elements with visual feedback. Mouse out animations provide closure, confirming that the user has moved away from an element and helping maintain visual consistency throughout the interface.

Targeted Animations

A powerful feature allows triggering animations on one element when interacting with another. This pattern uses selector attributes to connect trigger elements with target elements, enabling complex interactions like opening modals from trigger buttons, revealing hidden content panels, coordinating multiple animated elements, and creating guided tours and tutorials.

The targeted animation system creates relationships between elements, allowing you to build sophisticated interactive patterns without complex JavaScript. By declaratively defining these relationships in your HTML, you create interfaces that are both powerful and maintainable. This approach aligns with modern web development practices of separating behavior from structure.

Best Practices for User-Centered Design

Meaningful Motion Over Decorative Animation

Every animation should serve a purpose beyond visual appeal. Motion guides attention, communicates relationships, and provides feedback. When elements animate, users should understand why--they're revealing new content, highlighting important information, or indicating that an action has been recognized. Avoid animations that distract from core content without adding value, trigger too frequently creating visual noise, contradict the natural reading flow, or slow down content consumption unnecessarily.

Performance Optimization

Animation performance directly impacts user experience and search rankings. Each animation that causes layout recalculation or repaints can introduce jank, especially on lower-powered devices. Best practices include using CSS transforms and opacity animations that don't trigger layout, limiting the number of simultaneous animations, testing on actual mobile devices rather than desktop browsers, and monitoring frame rates during development. The Intersection Observer API that scrolly uses by default provides performance benefits over scroll event listeners. For sites where SEO performance is critical, these optimizations become even more important as search engines factor page speed into rankings.

Accessibility Considerations

Motion sensitivity affects a significant portion of users, and responsible implementation includes respecting prefers-reduced-motion media queries. When users or their system settings indicate preference for reduced motion, scrolly animations should be minimized or disabled. This CSS-based approach ensures that users who prefer reduced motion receive a static experience without JavaScript intervention, respecting their system preferences across all websites.

Mobile Responsiveness

The library provides granular control for different device types, allowing you to disable complex animations on mobile to preserve battery while maintaining full animation on desktop for rich experiences. Animation performance on mobile requires careful attention--test on actual devices during development and adjust complexity based on real-world performance rather than desktop benchmarks.

Implementation Examples

The following patterns demonstrate proven approaches for common scrolly implementations. Each example includes complete code and explains why the pattern works for user-centered design. These implementations balance visual impact with performance, accessibility, and maintainability.

Feature List with Scroll Reveal

For product feature lists, progressive reveal keeps users engaged as they scroll through your value proposition. The alternating left/right animations create visual interest while the staggered delays ensure each feature gets individual attention. This pattern works particularly well for landing pages where you want to guide visitors through your key benefits systematically.

Testimonials with Character Animation

Highlighting customer testimonials with character-by-character animation draws attention to the quote and creates anticipation before the full message reveals. This pattern builds credibility while creating a memorable moment that reinforces social proof. Combined with your conversion optimization strategy, testimonial animations can significantly impact trust-building.

Hero Section Animation

A common pattern involves animating the hero section as users arrive, creating an immediate impression of quality and attention to detail. The staggered timing creates a cascading effect where elements appear in sequence, drawing the eye from headline to description to call-to-action. This approach establishes visual hierarchy and guides users toward your primary conversion goal.

This pattern works best when animations are subtle and purposeful. The goal isn't to amaze users with complexity but to create a sense of momentum as they begin their journey through your site. By the time they reach the call-to-action, they're already engaged and primed to take action.

Conclusion

Scrolly brings scroll-driven animations within reach of any developer, regardless of animation experience. Its declarative approach through data attributes means you can add sophisticated effects without writing complex JavaScript, while its configuration options provide flexibility for advanced use cases. The library's zero-dependency architecture and performance-first design make it suitable for projects of any scale.

The key to successful implementation lies in user-centered design--animations should enhance the experience, not distract from content. Start with simple fade-in effects that guide attention through your content hierarchy. Experiment with character animations for headlines that need extra emphasis. Gradually build toward sophisticated coordinated sequences that tell visual stories as users explore.

By following the best practices outlined in this guide and testing across devices, you can create engaging, performant scroll experiences that delight users and reinforce your brand's commitment to quality. Whether you're building a simple portfolio site or a complex interactive story, scrolly provides the tools to bring your content to life as users explore. Our web development services can help you implement these techniques effectively across your entire site.

Sources

1. Scrolly.js Documentation - Official library documentation with complete API reference and examples
2. Scrolly.js GitHub Repository - Primary source with CSS animation integration and declarative data attributes
3. The Pudding: How to Implement Scrollytelling - Industry-standard implementation comparison and best practices
4. ScrollyTeller Documentation - JavaScript library for scroll-driven data stories
5. Scrollama.js - Modern Scrollytelling - Modern scrollytelling library using IntersectionObserver for performance