TODOvue Scroll Top (TvScrollTop)

A lightweight, customizable Vue 3 "scroll to top" button component with smooth animations, position variants, configurable threshold, and SSR support. Works seamlessly in Single Page Apps and Server-Side Rendered (SSR) environments like Nuxt 3.

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

Features

Smooth scroll to top with one click
Configurable visibility threshold (show button after X pixels scrolled)
Position variants: left or right side
Beautiful entrance/exit animations with rotation and bounce effects
Backdrop blur effect for modern UI
Automatic show/hide based on scroll position
SSR-safe (works with Nuxt 3 and other SSR frameworks)
Composable API (useScrollTop) for custom implementations
Keyboard accessible (focus states and ARIA labels)
Lightweight and tree-shakeable
TypeScript support

Installation

Using npm:

npm install @todovue/tv-scroll-top

Using yarn:

yarn add @todovue/tv-scroll-top

Using pnpm:

pnpm add @todovue/tv-scroll-top

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-scroll-top/style.css'
import { TvScrollTop } from '@todovue/tv-scroll-top'

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

For Nuxt 3/4:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@todovue/tv-scroll-top/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-scroll-top/style.css'
import TvScrollTop from '@todovue/tv-scroll-top'

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

Local import inside a component:

<script setup>
import { TvScrollTop } from '@todovue/tv-scroll-top'
import '@todovue/tv-scroll-top/style.css'
</script>

<template>
  <div>
    <!-- Your page content -->
    <div style="height: 2000px">
      Scroll down to see the button appear...
    </div>
    
    <!-- Scroll to top button (appears after scrolling 300px by default) -->
    <TvScrollTop />
  </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-scroll-top/nuxt']
})

Alternatively, you can manually add the CSS:

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

Then create a plugin file: plugins/tv-scroll-top.client.ts:

import { defineNuxtPlugin } from '#app'
import TvScrollTop from '@todovue/tv-scroll-top'

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

Use anywhere in your Nuxt app:

<template>
  <div>
    <NuxtPage />
    
    <!-- Scroll to top button -->
    <TvScrollTop :threshold="400" position="right" />
  </div>
</template>

Optional direct import (no plugin):

<script setup>
import { TvScrollTop } from '@todovue/tv-scroll-top'
</script>

Component Registration Options

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

Props

Prop	Type	Default	Description
threshold	Number	300	Scroll position (in pixels) after which the button becomes visible.
position	String	'right'	Position of the button: `'left'` or `'right'`.
showOnScrollUp	Boolean	false	When true, the button only appears when scrolling up (not down).

Prop Details

`threshold`

Controls when the scroll-to-top button appears. The button will show when the user has scrolled down more than this value (in pixels).

Example:

<TvScrollTop :threshold="500" />

`position`

Controls the horizontal position of the button on the screen.

Accepted values:

'right' - Button appears on the right side (default)
'left' - Button appears on the left side

Example:

<TvScrollTop position="left" />

`showOnScrollUp`

Controls whether the button should only appear when the user is scrolling up. When enabled, the button will hide when scrolling down and show when scrolling up (as long as the threshold is met).

Accepted values:

false - Button shows whenever scroll position exceeds threshold (default behavior)
true - Button only shows when scrolling up AND scroll position exceeds threshold

Example:

<!-- Button appears only when scrolling up -->
<TvScrollTop :show-on-scroll-up="true" />

This is particularly useful for a better user experience, as the button won't obstruct content while the user is reading down the page.

Composable API

TvScrollTop includes a composable useScrollTop that you can use to build custom scroll-to-top functionality.

`useScrollTop(threshold, showOnScrollUp)`

import { useScrollTop } from '@todovue/tv-scroll-top'

const { isVisible, scrollToTop } = useScrollTop(300, false)

Parameters:

threshold (Number|Ref): Scroll position in pixels (default: 300)
showOnScrollUp (Boolean|Ref): Whether to show the button only when scrolling up (default: false)

Returns:

isVisible (Ref): Reactive boolean indicating if scroll position is past the threshold (and scrolling direction if enabled)
scrollToTop (Function): Function to smoothly scroll to the top of the page

Example:

<script setup>
import { useScrollTop } from '@todovue/tv-scroll-top'

const { isVisible, scrollToTop } = useScrollTop(400, true)
</script>

<template>
  <button v-if="isVisible" @click="scrollToTop">
    Custom Scroll Top Button
  </button>
</template>

Usage Examples

Default (Right Position, 300px Threshold)

<script setup>
import { TvScrollTop } from '@todovue/tv-scroll-top'
import '@todovue/tv-scroll-top/style.css'
</script>

<template>
  <div>
    <div style="height: 2000px">
      <!-- Your content -->
    </div>
    
    <TvScrollTop />
  </div>
</template>

Left Position

<script setup>
import { TvScrollTop } from '@todovue/tv-scroll-top'
import '@todovue/tv-scroll-top/style.css'
</script>

<template>
  <div>
    <div style="height: 2000px">
      <!-- Your content -->
    </div>
    
    <TvScrollTop position="left" />
  </div>
</template>

Low Threshold (100px)

Perfect for shorter pages or when you want the button to appear quickly.

<script setup>
import { TvScrollTop } from '@todovue/tv-scroll-top'
import '@todovue/tv-scroll-top/style.css'
</script>

<template>
  <div>
    <div style="height: 2000px">
      <!-- Your content -->
    </div>
    
    <TvScrollTop :threshold="100" />
  </div>
</template>

High Threshold (600px)

For longer pages where you want the button to appear later.

<script setup>
import { TvScrollTop } from '@todovue/tv-scroll-top'
import '@todovue/tv-scroll-top/style.css'
</script>

<template>
  <div>
    <div style="height: 3000px">
      <!-- Your content -->
    </div>
    
    <TvScrollTop :threshold="600" />
  </div>
</template>

Show Only When Scrolling Up

The button only appears when the user scrolls up, preventing content obstruction while reading down the page.

<script setup>
import { TvScrollTop } from '@todovue/tv-scroll-top'
import '@todovue/tv-scroll-top/style.css'
</script>

<template>
  <div>
    <div style="height: 2000px">
      <!-- Your content -->
    </div>
    
    <TvScrollTop :show-on-scroll-up="true" />
  </div>
</template>

Custom Implementation with Composable

<script setup>
import { useScrollTop } from '@todovue/tv-scroll-top'

const { isVisible, scrollToTop } = useScrollTop(200, true)

const handleClick = () => {
  scrollToTop()
  console.log('Scrolling to top!')
}
</script>

<template>
  <Transition name="fade">
    <button 
      v-if="isVisible" 
      @click="handleClick"
      class="my-custom-scroll-button"
    >
      ↑ Top
    </button>
  </Transition>
</template>

<style scoped>
.my-custom-scroll-button {
  position: fixed;
  bottom: 20px;
  right: 20px;
  padding: 10px 20px;
  background: #007bff;
  color: white;
  border: none;
  border-radius: 5px;
  cursor: pointer;
}

.fade-enter-active, .fade-leave-active {
  transition: opacity 0.3s;
}
.fade-enter-from, .fade-leave-to {
  opacity: 0;
}
</style>

Animations

TvScrollTop includes beautiful built-in animations that differ based on position:

Right Position Animations

Enter: Slides in from right with rotation (180° to 0°), bounce effect, and scale
Leave: Slides out to right with rotation (0° to 180°) and scale down

Left Position Animations

Enter: Slides in from left with rotation (-180° to 0°), bounce effect, and scale
Leave: Slides out to left with rotation (0° to -180°) and scale down

Visual Effects

Smooth cubic-bezier timing functions for natural movement
Backdrop blur effect (10px) for modern glass-morphism look
Shadow elevation on hover (4px → 8px)
Scale transform on hover (1.05x) and active (1.02x)

Animations are implemented using Vue's <Transition> component and CSS keyframes.

Accessibility

ARIA Label: Button includes aria-label="Scroll to top" for screen readers
Keyboard Support: Fully keyboard accessible (can be focused and activated with Enter/Space)
Focus States: Clear focus indicators for keyboard navigation
Semantic HTML: Uses proper <button> element
SVG Icon: Uses semantic SVG with proper stroke and viewBox attributes

SSR Notes

SSR-Safe: No direct window/document access during module evaluation
Smart Guards: Uses typeof window !== 'undefined' checks
Lifecycle Hooks: Scroll listeners are added in onMounted hook
Cleanup: Automatically removes event listeners in onUnmounted
Nuxt 3 Compatible: Works seamlessly with Nuxt 3 out of the box
Hydration Safe: No hydration mismatches

Development

git clone https://github.com/TODOvue/tv-scroll-top.git
cd tv-scroll-top
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

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.github		.github
public		public
src		src
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
global.d.ts		global.d.ts
index.html		index.html
nuxt.js		nuxt.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vite.config.js		vite.config.js

Folders and files

Latest commit

History

Repository files navigation

TODOvue Scroll Top (TvScrollTop)

Table of Contents

Features

Installation

Importing Styles

For Vue/Vite SPA:

For Nuxt 3/4:

Quick Start (SPA)

Nuxt 4 / SSR Usage

Component Registration Options

Props

Prop Details

threshold

position

showOnScrollUp

Composable API

useScrollTop(threshold, showOnScrollUp)

Usage Examples

Default (Right Position, 300px Threshold)

Left Position

Low Threshold (100px)

High Threshold (600px)

Show Only When Scrolling Up

Custom Implementation with Composable

Animations

Right Position Animations

Left Position Animations

Visual Effects

Accessibility

SSR Notes

Development

Contributing

License

Attributions

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 4

Contributors

Uh oh!

Languages

`threshold`

`position`

`showOnScrollUp`

`useScrollTop(threshold, showOnScrollUp)`