TODOvue Progress Bar (TvProgressBar)

A lightweight, customizable Vue 3 reading progress bar component that tracks scroll position through content. Features smooth animations, flexible target selection, configurable offsets, and SSR support. Works seamlessly in Single Page Apps and Server-Side Rendered (SSR) environments like Nuxt 3.

Demo: https://ui.todovue.blog/progressbar

Table of Contents

• Features
• Installation
• Quick Start (SPA)
• Nuxt 4 / SSR Usage
• Component Registration Options
• Props
• Composable API
• Usage Examples
• Accessibility
• SSR Notes
• Development
• Contributing
• License

Features

• Real-time reading progress tracking based on scroll position
• Flexible target selection (CSS selector, element reference, or DOM element)
• Configurable height and color
• Support for Gradients: Pass multiple colors for a modern look
• Glow Effect: Optional neon glow that follows the progress bar
• Customizable Transitions: Configure duration and easing functions
• Vertical Orientation: Support for side progress bars (left/right)
• Reading Checkpoints: Display indicators at specific progress points (e.g., 25%, 50%, 75%)
• Progress Labels: Show percentage inside the bar or as a floating bubble
• Flexible Positioning: Fix the bar at the top, bottom, left, right, or use sticky behavior
• Top and bottom offset support for fixed headers/footers
• Smooth linear transitions with reduced motion support
• SSR-safe (works with Nuxt 3 and other SSR frameworks)
• Composable API (useProgressBar) for custom implementations
• ResizeObserver support for responsive content
• RequestAnimationFrame optimization for smooth performance
• Keyboard accessible with ARIA labels
• Lightweight and tree-shakeable
• TypeScript support

Installation

Using npm:

npm install @todovue/tv-progress-bar

Using yarn:

yarn add @todovue/tv-progress-bar

Using pnpm:

pnpm add @todovue/tv-progress-bar

Importing Styles

Important: You must explicitly import the stylesheet in your application.

For Vue/Vite SPA:

// main.ts
import { createApp } from 'vue'
import App from './App.vue'

import '@todovue/tv-progress-bar/style.css'
import { TvProgressBar } from '@todovue/tv-progress-bar'

const app = createApp(App)
app.component('TvProgressBar', TvProgressBar)
app.mount('#app')

For Nuxt 3/4:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@todovue/tv-progress-bar/nuxt'
  ]
})

Then register the component in a plugin as shown in the Nuxt 3 / SSR Usage section.

Quick Start (SPA)

Global registration (main.js / main.ts):

import { createApp } from 'vue'
import App from './App.vue'
import '@todovue/tv-progress-bar/style.css'
import TvProgressBar from '@todovue/tv-progress-bar'

createApp(App)
  .use(TvProgressBar) // enables <TvProgressBar /> globally
  .mount('#app')

Local import inside a component:

<script setup>
import { ref } from 'vue'
import { TvProgressBar } from '@todovue/tv-progress-bar'
import '@todovue/tv-progress-bar/style.css'

const articleContainer = ref(null)
</script>

<template>
  <div>
    <!-- Progress bar tracks the article container -->
    <TvProgressBar :target="articleContainer" />
    
    <!-- Your article content -->
    <article ref="articleContainer">
      <h1>My Article</h1>
      <p>Lorem ipsum dolor sit amet...</p>
      <!-- Long content here -->
    </article>
  </div>
</template>

Note: Don't forget to import the CSS in your main entry file as shown above.

Nuxt 4 / SSR Usage

First, add the module to your nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@todovue/tv-progress-bar/nuxt']
})

Alternatively, you can manually add the CSS:

// nuxt.config.ts
export default defineNuxtConfig({
  css: ['@todovue/tv-progress-bar/style.css'],
})

Then create a plugin file: plugins/tv-progress-bar.client.ts:

import { defineNuxtPlugin } from '#app'
import TvProgressBar from '@todovue/tv-progress-bar'

export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.vueApp.use(TvProgressBar)
})

Use anywhere in your Nuxt app:

<script setup>
import { ref } from 'vue'

const mainContent = ref(null)
</script>

<template>
  <div>
    <TvProgressBar :target="mainContent" :offset-top="60" />
    
    <main ref="mainContent">
      <NuxtPage />
    </main>
  </div>
</template>

Optional direct import (no plugin):

<script setup>
import { TvProgressBar } from '@todovue/tv-progress-bar'
</script>

Component Registration Options

Approach	When to use
Global via app.use(TvProgressBar)	Many usages across app / design system install
Local named import { TvProgressBar }	Isolated / code-split contexts
Direct default import import TvProgressBar from '@todovue/tv-progress-bar'	Single usage or manual registration

Props

Prop	Type	Default	Description
target	String | Object	'.container-blog'	CSS selector or element reference to track scroll progress.
offsetTop	Number	0	Top offset in pixels (useful for fixed headers).
offsetBottom	Number	0	Bottom offset in pixels (useful for fixed footers).
height	String	'4px'	Height of horizontal progress bar (CSS value).
width	String	'4px'	Width of vertical progress bar (CSS value).
zIndex	Number	1200	Z-index for the progress bar positioning.
disabled	Boolean	false	Whether the progress bar is enabled and visible.
color	String	''	Custom background color for the progress bar (CSS color value).
gradient	Array	[]	Array of colors for a linear gradient background.
glow	Boolean	false	Whether to enable the glow effect.
glowColor	String	''	Custom color for the glow effect.
duration	String	'120ms'	Transition duration (e.g., '300ms', '0.5s').
easing	String	'linear'	Transition easing function (e.g., 'ease-in-out').
orientation	String	'horizontal'	Bar orientation: 'horizontal' or 'vertical'.
position	String	'top' (horiz) / 'left' (vert)	Positioning: 'top', 'bottom', 'left', 'right', or 'sticky'.
showLabel	Boolean	false	Whether to show the percentage label.
labelPosition	String	'inside'	Label position: 'inside' or 'floating'.
checkpoints	Array	[]	Array of numbers (0-100) to show indicators on the bar.
modelValue	Number	null	Sets the progress manually (0-100). Overrides scroll tracking.

Prop Details

target

The element to track for reading progress. Can be:

• A CSS selector string (e.g., '.article', '#content')
• A template ref (e.g., ref(null))
• An HTMLElement reference

Example:

<script setup>
import { ref } from 'vue'

const articleRef = ref(null)
</script>

<template>
  <!-- Using template ref -->
  <TvProgressBar :target="articleRef" />
  <article ref="articleRef">...</article>
  
  <!-- Using CSS selector -->
  <TvProgressBar target="#my-article" />
  <article id="my-article">...</article>
</template>

offsetTop

Accounts for fixed headers or navigation bars at the top of the page. The progress calculation will consider this offset.

Example:

<!-- 60px offset for fixed header -->
<TvProgressBar :target="articleRef" :offset-top="60" />

offsetBottom

Accounts for fixed footers or bottom bars. The progress calculation will consider this offset.

Example:

<!-- 80px offset for fixed footer -->
<TvProgressBar :target="articleRef" :offset-bottom="80" />

height

Controls the thickness of the progress bar. Accepts any CSS height value.

Example:

<TvProgressBar :target="articleRef" height="8px" />
<TvProgressBar :target="articleRef" height="0.5rem" />

zIndex

Controls the stacking order of the progress bar. Default is 1200 to ensure it appears above most content.

Example:

<TvProgressBar :target="articleRef" :z-index="9999" />

disabled

Allows you to conditionally enable/disable the progress bar. When disabled, the bar won't be rendered.

Example:

<script setup>
import { ref } from 'vue'

const showProgress = ref(true)
</script>

<template>
  <TvProgressBar :target="articleRef" :disabled="showProgress" />
</template>

color

Custom color for the progress bar. Accepts any CSS color value. If not provided, uses the default theme color.

Example:

<TvProgressBar :target="articleRef" color="#42b983" />
<TvProgressBar :target="articleRef" color="rgb(66, 185, 131)" />
<TvProgressBar :target="articleRef" color="var(--primary-color)" />

gradient

Array of colors to create a linear gradient background. When provided, it overrides the color prop.

Example:

<TvProgressBar :target="articleRef" :gradient="['#f093fb', '#f5576c']" />
<TvProgressBar :target="articleRef" :gradient="['#84fab0', '#8fd3f4']" />

glow

Enables a shadow effect that follows the progress bar, giving it a depth or "neon" look.

Example:

<TvProgressBar :target="articleRef" glow />
<TvProgressBar :target="articleRef" color="#00f2fe" glow />

glowColor

Customizes the color of the glow effect. If not provided, it defaults to the color prop or the last color in the gradient.

Example:

<TvProgressBar :target="articleRef" glow glow-color="#ff00ff" />

duration

Sets the duration of the progress bar transition.

Example:

<TvProgressBar :target="articleRef" duration="300ms" />
<TvProgressBar :target="articleRef" duration="0.5s" />

easing

Sets the easing function for the progress bar transition.

Example:

<TvProgressBar :target="articleRef" easing="ease-in-out" />
<TvProgressBar :target="articleRef" easing="cubic-bezier(0.4, 0, 0.2, 1)" />

Composable API

TvProgressBar includes a composable useProgressBar that you can use to build custom progress tracking functionality.

useProgressBar(targetEl, options)

import { useProgressBar } from '@todovue/tv-progress-bar'

const targetEl = ref(null)
const { progress, progressPercent, recalculate } = useProgressBar(targetEl, {
  offsetTop: computed(() => 60),
  offsetBottom: computed(() => 0)
})

Parameters:

• targetEl (Ref): Reactive reference to the element to track
• options (Object): Configuration options
  • offsetTop (Number|Ref|ComputedRef): Top offset in pixels (default: 0)
  • offsetBottom (Number|Ref|ComputedRef): Bottom offset in pixels (default: 0)

Returns:

• progress (Ref): Reactive number between 0 and 1 representing scroll progress
• progressPercent (Ref): Reactive number between 0 and 100 (rounded)
• recalculate (Function): Function to manually trigger a progress recalculation

Example:

<script setup>
import { ref, computed } from 'vue'
import { useProgressBar } from '@todovue/tv-progress-bar'

const articleRef = ref(null)
const { progress, progressPercent, recalculate } = useProgressBar(articleRef, {
  offsetTop: computed(() => 60),
  offsetBottom: computed(() => 0)
})
</script>

<template>
  <div>
    <!-- Custom progress display -->
    <div class="custom-progress">
      Reading progress: {{ progressPercent }}%
    </div>
    
    <!-- Custom progress bar -->
    <div class="custom-bar">
      <div 
        class="custom-fill" 
        :style="{ width: `${progress * 100}%` }"
      />
    </div>
    
    <article ref="articleRef">
      <!-- Your content -->
    </article>
    
    <button @click="recalculate">Recalculate Progress</button>
  </div>
</template>

<style scoped>
.custom-progress {
  position: fixed;
  top: 10px;
  right: 10px;
  background: rgba(0, 0, 0, 0.7);
  color: white;
  padding: 8px 12px;
  border-radius: 4px;
  font-size: 14px;
}

.custom-bar {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  height: 4px;
  background: rgba(0, 0, 0, 0.1);
}

.custom-fill {
  height: 100%;
  background: #42b983;
  transition: width 120ms linear;
}
</style>

Usage Examples

Default (CSS Selector)

<script setup>
import { TvProgressBar } from '@todovue/tv-progress-bar'
import '@todovue/tv-progress-bar/style.css'
</script>

<template>
  <div>
    <TvProgressBar target=".article-content" />
    
    <article class="article-content">
      <h1>My Article</h1>
      <p>Lorem ipsum dolor sit amet...</p>
      <!-- Your long content -->
    </article>
  </div>
</template>

Using Template Ref

<script setup>
import { ref } from 'vue'
import { TvProgressBar } from '@todovue/tv-progress-bar'
import '@todovue/tv-progress-bar/style.css'

const articleContainer = ref(null)
</script>

<template>
  <div>
    <TvProgressBar :target="articleContainer" />
    
    <article ref="articleContainer">
      <h1>My Article</h1>
      <p>Lorem ipsum dolor sit amet...</p>
      <!-- Your long content -->
    </article>
  </div>
</template>

Custom Color

<script setup>
import { ref } from 'vue'
import { TvProgressBar } from '@todovue/tv-progress-bar'
import '@todovue/tv-progress-bar/style.css'

const articleContainer = ref(null)
</script>

<template>
  <div>
    <TvProgressBar 
      :target="articleContainer" 
      color="#42b983" 
    />
    
    <article ref="articleContainer">
      <h1>My Article</h1>
      <p>Lorem ipsum dolor sit amet...</p>
    </article>
  </div>
</template>

Custom Height

<script setup>
import { ref } from 'vue'
import { TvProgressBar } from '@todovue/tv-progress-bar'
import '@todovue/tv-progress-bar/style.css'

const articleContainer = ref(null)
</script>

<template>
  <div>
    <TvProgressBar 
      :target="articleContainer" 
      height="8px" 
    />
    
    <article ref="articleContainer">
      <h1>My Article</h1>
      <p>Lorem ipsum dolor sit amet...</p>
    </article>
  </div>
</template>

Gradient Support

<script setup>
import { ref } from 'vue'
import { TvProgressBar } from '@todovue/tv-progress-bar'
import '@todovue/tv-progress-bar/style.css'

const articleContainer = ref(null)
</script>

<template>
  <div>
    <TvProgressBar 
      :target="articleContainer" 
      :gradient="['#f093fb', '#f5576c']"
      height="6px"
    />
    
    <article ref="articleContainer">
      <h1>My Article with Gradient</h1>
      <p>Scroll to see the gradient progress bar...</p>
    </article>
  </div>
</template>

Glow Effect

<script setup>
import { ref } from 'vue'
import { TvProgressBar } from '@todovue/tv-progress-bar'
import '@todovue/tv-progress-bar/style.css'

const articleContainer = ref(null)
</script>

<template>
  <div>
    <TvProgressBar 
      :target="articleContainer"
      color="#00f2fe"
      glow
      height="4px"
    />
    
    <article ref="articleContainer">
      <h1>Neon Glow Progress</h1>
      <p>Notice the subtle glow under the bar...</p>
    </article>
  </div>
</template>

Custom Transitions

<script setup>
import { ref } from 'vue'
import { TvProgressBar } from '@todovue/tv-progress-bar'
import '@todovue/tv-progress-bar/style.css'

const articleContainer = ref(null)
</script>

<template>
  <div>
    <TvProgressBar 
      :target="articleContainer"
      duration="800ms"
      easing="cubic-bezier(0.68, -0.55, 0.265, 1.55)"
      color="#3f51b5"
    />
    
    <article ref="articleContainer">
      <h1>Bouncy Progress Bar</h1>
      <p>Scroll fast to see the custom easing effect...</p>
    </article>
  </div>
</template>

### Vertical Orientation
```vue
<template>
  <TvProgressBar 
    target=".content" 
    orientation="vertical" 
    position="left" 
    width="6px" 
    color="#4f46e5" 
  />
</template>

Reading Checkpoints

<template>
  <TvProgressBar 
    target=".content" 
    :checkpoints="[25, 50, 75]" 
    color="#f59e0b" 
  />
</template>

Floating Percentage Label

<template>
  <TvProgressBar 
    target=".content" 
    show-label 
    label-position="floating" 
    color="#10b981" 
    glow 
  />
</template>

Sticky Position (Inside Container)

<template>
  <div class="relative-container">
    <TvProgressBar 
      target=".content" 
      position="sticky" 
      color="#ec4899" 
    />
    <div class="content">...</div>
  </div>
</template>

### With Fixed Header (Offset Top)
```vue
<script setup>
import { ref } from 'vue'
import { TvProgressBar } from '@todovue/tv-progress-bar'
import '@todovue/tv-progress-bar/style.css'

const articleContainer = ref(null)
</script>

<template>
  <div>
    <header style="position: fixed; top: 0; height: 60px;">
      <!-- Fixed header content -->
    </header>
    
    <TvProgressBar 
      :target="articleContainer" 
      :offset-top="60" 
    />
    
    <article ref="articleContainer" style="margin-top: 60px;">
      <h1>My Article</h1>
      <p>Lorem ipsum dolor sit amet...</p>
    </article>
  </div>
</template>

With Fixed Header and Footer

<script setup>
import { ref } from 'vue'
import { TvProgressBar } from '@todovue/tv-progress-bar'
import '@todovue/tv-progress-bar/style.css'

const articleContainer = ref(null)
</script>

<template>
  <div>
    <header style="position: fixed; top: 0; height: 60px;">
      <!-- Fixed header -->
    </header>
    
    <TvProgressBar 
      :target="articleContainer" 
      :offset-top="60" 
      :offset-bottom="80" 
    />
    
    <article ref="articleContainer" style="margin: 60px 0 80px;">
      <h1>My Article</h1>
      <p>Lorem ipsum dolor sit amet...</p>
    </article>
    
    <footer style="position: fixed; bottom: 0; height: 80px;">
      <!-- Fixed footer -->
    </footer>
  </div>
</template>

### Loader Mode
Use the `modelValue` prop to manually control the progress, making it function like a loader.

```vue
<script setup>
import { ref, onMounted } from 'vue'
import { TvProgressBar } from '@todovue/tv-progress-bar'

const progress = ref(0)
const isLoading = ref(true)

onMounted(() => {
  const interval = setInterval(() => {
    if (progress.value < 100) {
      progress.value += 1
    } else {
      clearInterval(interval)
      isLoading.value = false
    }
  }, 50)
})
</script>

<template>
  <TvProgressBar 
    :model-value="progress"
    :show-label="true"
    color="#3b82f6"
  />
</template>

### Conditional Rendering
```vue
<script setup>
import { ref } from 'vue'
import { TvProgressBar } from '@todovue/tv-progress-bar'
import '@todovue/tv-progress-bar/style.css'

const articleContainer = ref(null)
const showProgress = ref(true)
</script>

<template>
  <div>
    <button @click="showProgress = !showProgress">
      Toggle Progress Bar
    </button>
    
    <TvProgressBar 
      :target="articleContainer" 
      :disabled="showProgress" 
    />
    
    <article ref="articleContainer">
      <h1>My Article</h1>
      <p>Lorem ipsum dolor sit amet...</p>
    </article>
  </div>
</template>

All Props Combined

<script setup>
import { ref } from 'vue'
import { TvProgressBar } from '@todovue/tv-progress-bar'
import '@todovue/tv-progress-bar/style.css'

const articleContainer = ref(null)
</script>

<template>
  <div>
    <TvProgressBar 
      :target="articleContainer"
      :offset-top="60"
      :offset-bottom="40"
      height="6px"
      color="#ff6b6b"
      :z-index="9999"
      disabled
    />
    
    <article ref="articleContainer">
      <h1>My Article</h1>
      <p>Lorem ipsum dolor sit amet...</p>
    </article>
  </div>
</template>

Custom Implementation with Composable

<script setup>
import { ref, computed } from 'vue'
import { useProgressBar } from '@todovue/tv-progress-bar'

const contentRef = ref(null)
const { progress, progressPercent, recalculate } = useProgressBar(contentRef, {
  offsetTop: computed(() => 0),
  offsetBottom: computed(() => 0)
})
</script>

<template>
  <div>
    <!-- Circular progress indicator -->
    <div class="circular-progress">
      <svg width="60" height="60">
        <circle 
          cx="30" 
          cy="30" 
          r="25" 
          fill="none" 
          stroke="#e0e0e0" 
          stroke-width="5"
        />
        <circle 
          cx="30" 
          cy="30" 
          r="25" 
          fill="none" 
          stroke="#42b983" 
          stroke-width="5"
          :stroke-dasharray="`${progress * 157} 157`"
          transform="rotate(-90 30 30)"
        />
      </svg>
      <span class="percentage">{{ progressPercent }}%</span>
    </div>
    
    <article ref="contentRef">
      <h1>Custom Progress Indicator</h1>
      <p>Scroll to see the circular progress...</p>
      <!-- Your content -->
    </article>
  </div>
</template>

<style scoped>
.circular-progress {
  position: fixed;
  bottom: 20px;
  right: 20px;
  display: flex;
  align-items: center;
  justify-content: center;
}

.percentage {
  position: absolute;
  font-size: 12px;
  font-weight: bold;
  color: #42b983;
}
</style>

Accessibility

• ARIA Attributes: Progress bar includes proper ARIA attributes:
  • role="progressbar"
  • aria-label="Reading progress"
  • aria-valuemin="0"
  • aria-valuemax="100"
  • aria-valuenow (dynamically updated percentage)
• Pointer Events: Progress bar uses pointer-events: none to not interfere with page interactions
• Reduced Motion: Respects prefers-reduced-motion media query to disable transitions for users who prefer reduced motion
• Semantic HTML: Uses semantic div elements with proper ARIA roles
• Visual Feedback: Clear visual indication of reading progress

SSR Notes

• SSR-Safe: No direct window/document access during module evaluation
• Smart Guards: Uses typeof window !== 'undefined' checks throughout
• Lifecycle Hooks: Scroll listeners and observers are added in onMounted hook
• Cleanup: Automatically removes event listeners and observers in onBeforeUnmount
• Nuxt 3 Compatible: Works seamlessly with Nuxt 3 out of the box
• Hydration Safe: No hydration mismatches
• Performance: Uses requestAnimationFrame for smooth updates
• ResizeObserver: Automatically recalculates on content resize
• Passive Listeners: Scroll event listeners use passive: true for better performance

Development

git clone https://github.com/TODOvue/tv-progress-bar.git
cd tv-progress-bar
npm install
npm run dev     # run demo playground
npm run build   # build library

Local demo served from Vite using index.html and demo examples in src/demo.

Contributing

PRs and issues welcome. See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

License

MIT © TODOvue

Attributions

Crafted for the TODOvue component ecosystem