Vanilla Scroll Sky: Pure CSS Scrollytelling Library

Vanilla Scroll Sky is a pure CSS scrollytelling library that creates sticky image reveals and scroll-driven caption animations with a single stylesheet.

Sticky images animate into view as the user scrolls, paired with optional captions that glide across the screen.

The library uses only native browser features: CSS Custom Properties, @scope, @layer, container queries, position: sticky, and the CSS animation-timeline: view() API.

No JavaScript, no build step, no framework.

Features:

• Creates sticky image storytelling sections.
• Reveals images during page scroll.
• Moves captions across the viewport.
• Supports per-section visual tuning.
• Uses normal HTML markup.
• Organizes component styles cleanly.
• Supports responsive caption spacing.
• Respects reduced motion preferences.
• Keeps content readable in fallback states.

Use Cases:

• Editorial long-form articles where each section reveals a full-bleed photograph as the reader scrolls.
• Portfolio pages that animate project images into view alongside brief project descriptions.
• Product landing pages that pair hero photography with overlaid marketing copy in a scroll-driven sequence.
• Storytelling microsites where sequential image reveals guide the reader through a visual narrative.

How to use it:

1. Link the core stylesheet before your own CSS.

<link rel="stylesheet" href="/assets/css/vanilla-scroll-sky.css">

2. If your project already uses CSS Cascade Layers, import the file into your components layer to keep specificity under control:

/* Define your layer order first */
@layer base, components, utilities;

/* Then import Vanilla Scroll Sky into the components layer */
@import url("/assets/css/vanilla-scroll-sky.css") layer(components);

3. Enable an image to slide in from the left and stick while the user scrolls past the section:

<!-- The .vss class activates the utility. -->
<!-- .vss--image-left sets the reveal direction. -->
<section class="vss vss--image-left">
  <!-- Wrap your image inside .vss__image -->
  <div class="vss__image">
    <img src="/photos/mountain-trail.jpg" alt="A rocky mountain trail at dawn">
  </div>
</section>

4. Create a sticky image with a moving caption:

<!-- Combine an image direction class and a caption motion class on the same element -->
<section class="vss vss--image-right vss--caption-left-center">
  <div class="vss__image">
    <img src="/photos/coastal-cliffs.jpg" alt="Limestone cliffs meeting the Atlantic Ocean">
  </div>
  <!-- Caption content is normal HTML: headings, paragraphs, links -->
  <div class="vss__caption">
    <h2>The Atlantic Margin</h2>
    <p>
      These cliffs took three hundred million years to form. The ocean
      carved the last ten metres in a single winter storm in 2009.
    </p>
  </div>
</section>

5. Each .vss section accepts inline CSS Custom Properties to override timing, dimensions, and motion independently. This lets two sections on the same page behave differently with no extra CSS.

<!--
  This section uses a taller image, a longer scene duration,
  a delayed caption entrance, and a subdued caption slide distance.
-->
<section
  class="vss vss--image-bottom vss--caption-right-center"
  style="
    --vss-image-height: 70svh;
    --vss-scene-duration: 260svh;
    --vss-caption-delay: 50svh;
    --vss-caption-motion-distance: 5rem;
    --vss-image-stick-top: 4rem;
  "
>
  <div class="vss__image">
    <img
      src="/photos/forest-canopy.jpg"
      alt="Looking up through a dense forest canopy in autumn"
      <!-- object-fit and object-position are controlled by CSS custom properties, not HTML attributes -->
    >
  </div>
  <div class="vss__caption">
    <h2>Canopy Layer</h2>
    <p>
      The forest ceiling intercepts ninety percent of available light.
      What reaches the ground shapes every species that lives there.
    </p>
  </div>
</section>

<!--
  A second section immediately after, with a strong left-entry reveal
  and a pass-through caption for a short label.
-->
<section
  class="vss vss--image-left vss--caption-right-left"
  style="
    --vss-image-start-offset: 100vw;
    --vss-caption-motion-distance: 60vw;
    --vss-scene-duration: 180svh;
  "
>
  <div class="vss__image">
    <img src="/photos/river-bend.jpg" alt="Aerial view of a river bend in early spring">
  </div>
  <!-- Short label using pass-through motion -->
  <div class="vss__caption">
    <p>River Bend, 2024</p>
  </div>
</section>

6. Image Reveal Direction Classes:

• vss--image-left: Image enters from the left.
• vss--image-right: Image enters from the right.
• vss--image-top: Image enters from the top.
• vss--image-bottom: Image enters from the bottom.
• vss--image-none: Image appears in place with no translate animation.

7. Caption Motion Classes:

• vss--caption-left-center: Caption slides from left to center. Best for body text.
• vss--caption-right-center: Caption slides from right to center. Best for body text.
• vss--caption-left-right: Caption passes from left through to right. Use for short labels.
• vss--caption-right-left: Caption passes from right through to left. Use for short labels.

8. Available CSS Custom Properties. Set these on the .vss element as inline styles to configure each section individually.

Timing and Layout

• --vss-scene-duration (length): Total scroll height of the section. Default: 220svh.
• --vss-caption-delay (length): How far the user scrolls before the caption begins animating. Default: 40svh.
• --vss-scene-exit-space (length): Padding at the bottom of the section to give the content room to exit. Default: 55svh.
• --vss-image-stick-top (length): Top offset for the sticky image, useful when a fixed header is present. Default: 0.
• --vss-image-height (length): Height of the sticky image container. Default: 66svh.

Image Reveal

• --vss-image-start-offset (length): Distance the image travels during the reveal animation. Default: 4rem.
• --vss-image-start-scale (number): Scale factor of the image at the start of the reveal. Default: 0.96.
• --vss-image-fit (keyword): Maps to object-fit on the <img> element. Default: cover.
• --vss-image-position (keyword or position): Maps to object-position on the <img> element. Default: center.

Caption

• --vss-caption-motion-distance (length): Horizontal travel distance for caption motion classes. Default: 80vw.
• --vss-caption-max-width (length): Maximum width of the caption card. Default: 52rem.
• --vss-caption-padding (length): Padding inside the caption card. Default: clamp(1.5rem, 4vw, 3rem).

9. All properties accept standard CSS values and functions. clamp() and calc() both work inline:

<section
  class="vss vss--image-bottom vss--caption-left-center"
  style="
    --vss-image-height: clamp(28rem, 65svh, 44rem);
    --vss-scene-duration: calc(190svh + 20rem);
    --vss-caption-delay: clamp(18rem, 35svh, 32rem);
    --vss-caption-motion-distance: clamp(8rem, 40vw, 34rem);
  "
>

Alternatives:

• ScrollReveal: A JavaScript library that animates elements as they enter the viewport.
• AOS (Animate On Scroll): A data-attribute-driven scroll animation library.
• Scrollama: A JavaScript scrollytelling library built on IntersectionObserver.
• Locomotive Scroll: A smooth-scroll library with scroll-triggered class hooks.

FAQs:

Q: How do I account for a fixed navigation bar at the top of the page?
A: Set --vss-image-stick-top to the height of your header. For a 64px header, use style="--vss-image-stick-top: 4rem;" on the .vss element. This pushes the sticky image down so it clears the navigation.

Q: Can I use video instead of an image inside .vss__image?
A: Yes. The internal CSS targets img, svg, and video elements inside .vss__image with the same width: 100%; height: 100%; object-fit rules.

Q: My caption text inherits an unexpected font or color from my site’s base styles. How do I fix it?
A: Vanilla Scroll Sky uses @scope, not Shadow DOM, so inherited CSS properties like font-family and color pass through from your page styles. Override them directly on .vss__caption in your own stylesheet, or set inline style properties on the caption element itself.

Q: Does the library support multiple sections on one page?
A: Yes. Each .vss section is fully independent. Custom properties set on one section do not affect any other. You can mix image directions, caption motion classes, and custom property values freely across sections on the same page.

The post Vanilla Scroll Sky: Pure CSS Scrollytelling Library appeared first on CSS Script.