starlight-scroll-to-top 🚀

A plugin for Astro Starlight that adds a "scroll to top" button to your documentation site.

Features

The button appears when users scroll down the page, providing an easy way to navigate back to the top of long documentation pages.

• Smooth scrolling option for a better user experience,
• Light and dark theme support,
• Highly configurable appearance and behavior,
• Uses Starlight's --sl- prefixed CSS variables for consistent styling,
• Responsive design works on all devices,
• Configurable button position (left, center, or right),
• Customizable SVG icon,
• Optional scroll progress ring indicator,
• Customizable progress ring colors,
• Internationalization (I18N) support with automatic language detection and intelligent fallback,
• Configurable homepage visibility control.

Installation

npm install starlight-scroll-to-top

Usage

Add the plugin to your astro.config.mjs file:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import starlightScrollToTop from 'starlight-scroll-to-top';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [starlightScrollToTop()]
    })
  ]
});

Configuration

All options are optional with sensible defaults. You can customize the plugin with the following options:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import starlightScrollToTop from 'starlight-scroll-to-top';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [
        starlightScrollToTop({
          // Button position
          position: 'left',          
          // Tooltip text (supports I18N)
          tooltipText: {
            'en': 'Scroll to top',
            'es': 'Ir arriba',
            'fr': 'Retour en haut',
            'pt': 'Voltar ao topo',
            'de': 'Nach oben scrollen'
          },          
          showTooltip: true,
          // Use smooth scrolling
          smoothScroll: true,        
          // Visibility threshold (show after scrolling 300px)
          threshold: 300,          
          // Customize the SVG icon
          svgPath: 'M25 42 12 29 42 29Z',    
          svgStrokeWidth: 1, 
          borderRadius: '50',
          // Show scroll progress ring
          showProgressRing: true,
          // Customize progress ring color
          progressRingColor: '#ff6b6b',
          // Control homepage visibility
          showOnHomepage: false,
        })
      ]
    })
  ]
});

Documentation

For more details, check out the plugin documentation.

License

Licensed under the MIT License, Copyright © frostybee.

See LICENSE for more information.