Ermine UI

Scroll progress

A thin bar across the top that fills as the page, or one article, is read.

See it liveSource on GitHub

Install

If this is the first component in the project, set up once. This writes ermine.json and copies the theme stylesheet. The installation guide covers Vue, Nuxt and Astro.

npx ermineui init
pnpm dlx ermineui init
yarn dlx ermineui init
bunx ermineui init

Then add the component:

npx ermineui add scroll-progress
pnpm dlx ermineui add scroll-progress
yarn dlx ermineui add scroll-progress
bunx ermineui add scroll-progress

That copies 2 files into src/components/ui/scroll-progress/. Files you already have are kept.

Use

import { ScrollProgress } from '@/components/ui/scroll-progress'
<ScrollProgress />                         <!-- the whole page; target="#article" for one element -->
<section v-reveal>…</section>              <!-- v-reveal="120" delays it by 120ms -->
<CountUp :value="1284306" />
<Stat label="Deployments" :value="21480" count-up />

In Nuxt, with the auto-import setting, the tags work in templates without the import. In Astro, use it inside a Vue island.

What gets copied

FileWhere it goes
ScrollProgress.vuesrc/components/ui/scroll-progress/ScrollProgress.vue
index.tssrc/components/ui/scroll-progress/index.ts

The folders are the suggested ones. ermine.json says where yours are.

Source

This is exactly what the command copies. To install by hand, create each file below and the helpers listed above.

ScrollProgress.vue 71 lines
<script setup lang="ts">
import { onBeforeUnmount, onMounted, ref } from 'vue'

const props = defineProps<{
  /** Measure progress through one element (an article) instead of the whole page: a CSS selector or an element. */
  target?: string | HTMLElement
}>()

/** How far through, from 0 to 1. */
const progress = ref(0)
let frame = 0

function measure() {
  const el = typeof props.target === 'string' ? document.querySelector<HTMLElement>(props.target) : props.target
  if (el) {
    // From the moment its top reaches the top of the window to the moment its bottom reaches the bottom.
    const box = el.getBoundingClientRect()
    const distance = box.height - window.innerHeight
    progress.value = distance > 0 ? Math.max(0, Math.min(-box.top / distance, 1)) : box.top <= 0 ? 1 : 0
    return
  }
  const distance = document.documentElement.scrollHeight - window.innerHeight
  progress.value = distance > 0 ? Math.max(0, Math.min(window.scrollY / distance, 1)) : 0
}

// At most once per frame, however often scroll events fire.
function schedule() {
  cancelAnimationFrame(frame)
  frame = requestAnimationFrame(measure)
}

onMounted(() => {
  measure()
  window.addEventListener('scroll', schedule, { passive: true })
  window.addEventListener('resize', schedule)
})

onBeforeUnmount(() => {
  cancelAnimationFrame(frame)
  window.removeEventListener('scroll', schedule)
  window.removeEventListener('resize', schedule)
})
</script>

<template>
  <!-- Decoration: the scrollbar already tells assistive technology where the reader is. -->
  <div class="er-scroll-progress" aria-hidden="true" :style="{ '--er-scroll-progress': progress }">
    <div />
  </div>
</template>

<style>
@layer components {
  .er-scroll-progress {
    position: fixed;
    inset: 0 0 auto;
    z-index: var(--er-z-overlay);
    height: 3px;
    pointer-events: none;
  }

  /* Scaled, not resized, so filling it never makes the browser lay the page out again. */
  .er-scroll-progress div {
    height: 100%;
    background: var(--er-primary);
    transform: scaleX(var(--er-scroll-progress, 0));
    transform-origin: left;
  }
}
</style>
index.ts 3 lines
/** Scroll progress — a thin bar across the top that fills as the page, or one article, is read. */
export { default as ScrollProgress } from './ScrollProgress.vue'