Skip to content
Starlight Scroll to Top

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

Section titled “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.

astro.config.mjs
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

Section titled “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

Section titled “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

Section titled “tooltipText”
  • Type: string
  • Default: 'Scroll to top'
  • Description: Defines the text displayed in the tooltip when hovering over the button. Customize this to provide a user-friendly message.

showTooltip

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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').

Example Configuration

Section titled “Example Configuration”
astro.config.mjs
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',
       })
       ]
     })
   ]
 });