Configuration

The Astro Starlight Scroll to Top plugin provides a variety of configuration options to customize the appearance and behavior of the scroll-to-top button. You can easily adjust these settings to fit your website’s design and user experience.

Configuring Scroll to Top

The Starlight Scroll to Top plugin can be configured in your astro.config.mjs file. To do this, you need to import the plugin and add it to the integrations array in your Astro configuration.

Refer to the example below for a complete configuration.

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

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightScrollToTop({
               // Configuration options go here.
        }),
      ],
      title: 'My Docs',
    }),
  ],
})

Configuration Options

The Starlight scroll-to-top plugin accepts an object with the following options. You can customize these options to fit your needs. The default values are provided for each option.

`position`

Type: 'left' | 'right' | 'center'
Default: 'right'
Description: Specifies the position of the scroll-to-top button on the page. Choose 'left' to place the button on the left side, 'right' for the right side, or 'center' to place the button in middle of the page.

`tooltipText`

Type: string | object
Default: 'Scroll to top'
Description: Defines the text displayed in the tooltip when hovering over the button. Can be a simple string for single language support, or an object for internationalization (I18N) support.

Single Language

tooltipText: 'Back to top'

Internationalization (I18N)

For multi-language support, pass an object with language codes as keys. The plugin automatically detects the document’s language from <html lang="..."> and uses the appropriate translation:

tooltipText: {
  'en': 'Scroll to top',
  'es': 'Ir arriba',
  'fr': 'Retour en haut',
  'de': 'Nach oben scrollen',
  'pt': 'Voltar ao topo',
  'ja': 'トップへ戻る',
  'zh': '回到顶部'
}

Language Variants Support

The plugin supports language variants (like pt-BR, en-US) with intelligent fallback:

tooltipText: {
  'en': 'Scroll to top',
  'pt': 'Voltar ao topo',           // Base Portuguese (fallback for both variants)
  'pt-br': 'Voltar ao topo',       // Brazilian Portuguese (optional override)
  'pt-pt': 'Voltar ao início'      // European Portuguese (optional override)
}

Fallback Strategy:

Exact match: pt-BR → looks for 'pt-br'
Base language: If not found → looks for 'pt'
English fallback: If no Portuguese → looks for 'en'
Default: Finally uses 'Scroll to top'

This means you can provide just the base language (e.g., 'pt') to cover all variants, or specify regional differences when needed.

`showTooltip`

Type: boolean
Default: false
Description: Determines whether the tooltip is shown when hovering over the button. Set to true to enable the tooltip, or false to disable it.

`smoothScroll`

Type: boolean
Default: true
Description: Controls the scrolling behavior. Set to true to enable smooth scrolling when the button is clicked, or false for instant scrolling.

`threshold`

Type: number
Default: 30
Description: Indicates the percentage of the total page height (not limited to the viewport) that must be scrolled before the button is shown. The value should be a number between 10 and 99. For instance, setting it to 30 means the button will appear after 30% of the full page has been scrolled.

`svgPath`

Type: string
Default: 'M18 15l-6-6-6 6'
Description: Defines the d attribute of the SVG path element, which determines the shape of the icon. The default value creates an upward arrow. Provide a valid SVG path string to customize the icon.

`svgStrokeWidth`

Type: number
Default: 2
Description: Specifies the stroke width of the SVG icon. Adjust this to make the icon’s outline thicker or thinner.

`borderRadius`

Type: string
Default: '15'
Description: Sets the border radius of the button, controlling the roundness of its corners. Use a percentage value (e.g., '50' for a circular button, '0' for a square button) or a valid CSS length value (e.g., '15px').

`showProgressRing`

Type: boolean
Default: false
Description: Determines whether to display a circular progress ring around the button that indicates scroll progress. When enabled, the ring fills as the user scrolls down the page, providing visual feedback of reading progress.

`progressRingColor`

Type: string
Default: 'yellow'
Description: Specifies the color of the scroll progress ring. Accepts any valid CSS color value including hex codes (e.g., '#ff6b6b'), RGB/RGBA values (e.g., 'rgba(255, 107, 107, 0.8)'), CSS color names (e.g., 'orange'), or CSS custom properties (e.g., 'var(--my-custom-color)'). The default yellow color provides good contrast against the button’s accent color background.

`showOnHomepage`

Type: boolean
Default: false
Description: Controls whether the scroll-to-top button appears on the homepage or landing pages. When set to false (default), the button will be hidden on pages containing hero sections, landing page elements, or homepage-specific content. Set to true to show the button on all pages including the homepage.

Example Configurations

Basic Configuration

export default defineConfig({
   integrations: [
     starlight({
       plugins: [
        starlightScrollToTop({
            position: 'left',
            tooltipText: 'Back to top',
            showTooltip: true,
            smoothScroll: true,
            threshold: 20,
            svgPath: 'M18 15l-6-6-6 6',
            svgStrokeWidth: 1,
            borderRadius: '50',
            showProgressRing: true,
            progressRingColor: '#ff6b6b',
            showOnHomepage: false,  // Hide on homepage (default)
       })
       ]
     })
   ]
 });

Multi-language Configuration

Perfect for international documentation sites with Starlight’s built-in I18N support:

export default defineConfig({
   integrations: [
     starlight({
       plugins: [
        starlightScrollToTop({
            position: 'right',
            tooltipText: {
              'en': 'Scroll to top',
              'es': 'Ir arriba',
              'fr': 'Retour en haut',
              'de': 'Nach oben scrollen',
              'pt': 'Voltar ao topo',        // Covers pt-BR and pt-PT
              'pt-br': 'Voltar ao topo',    // Brazilian Portuguese override
              'pt-pt': 'Voltar ao início',  // European Portuguese override
              'ja': 'トップへ戻る',
              'ko': '맨 위로',
              'zh': '回到顶部',
              'ar': 'العودة إلى الأعلى'
            },
            showTooltip: true,
            smoothScroll: true,
            threshold: 25,
            showProgressRing: true,
            progressRingColor: 'var(--sl-color-accent)',
            showOnHomepage: true,   // Show on all pages including homepage
       })
       ]
     })
   ]
 });