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 20% down)
          threshold: 20,          
          // 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.