ScrollSpy Component

A navigation component that tracks scroll position and highlights the currently visible section. Supports smooth scrolling, sticky positioning, custom scroll containers, offset handling, and active state callbacks for building interactive page or documentation navigation.

Installation

Install the required packages:

pnpm i -D flowbite-svelte flowbite

This installs `flowbite-svelte` (Svelte components) and `flowbite` as development dependencies.

Basic Usage

The simplest way to use ScrollSpy is to provide an array of navigation items:

<script>
  import { ScrollSpy } from 'flowbite-svelte';
  
  const items = [
    { id: 'section-1', label: 'Section 1' },
    { id: 'section-2', label: 'Section 2' },
    { id: 'section-3', label: 'Section 3' }
  ];
</script>

<ScrollSpy {items} />

<section id="section-1">...</section>
<section id="section-2">...</section>
<section id="section-3">...</section>

Note: Make sure each section has an id attribute that matches the id in your items array.

Features

Custom Positioning

You can position the navigation on the top, left, or right:

<script>
  import { ScrollSpy } from 'flowbite-svelte';
  
  const items = [
    { id: 'section-1', label: 'Section 1' },
    { id: 'section-2', label: 'Section 2' },
    { id: 'section-3', label: 'Section 3' }
  ];
</script>

<ScrollSpy {items} position="left" />

<section id="section-1">...</section>
<section id="section-2">...</section>
<section id="section-3">...</section>

Offset for Fixed Headers

If you have a fixed header, use the offset prop to adjust when sections are considered "active":

<script>
  import { ScrollSpy } from 'flowbite-svelte';
  
  const items = [
    { id: 'section-1', label: 'Section 1' },
    { id: 'section-2', label: 'Section 2' },
    { id: 'section-3', label: 'Section 3' }
  ];
</script>

<ScrollSpy {items} offset={80} />

<section id="section-1">...</section>
<section id="section-2">...</section>
<section id="section-3">...</section>

Custom Active Styling

Customize the appearance of active navigation items:

<script>
  import { ScrollSpy } from 'flowbite-svelte';
  
  const items = [
    { id: 'section-1', label: 'Section 1' },
    { id: 'section-2', label: 'Section 2' },
    { id: 'section-3', label: 'Section 3' }
  ];
</script>

<ScrollSpy
  {items}
  activeClass="text-purple-600 border-purple-600 font-bold"
/>

<section id="section-1">...</section>
<section id="section-2">...</section>
<section id="section-3">...</section>

Props Reference

Prop	Type	Default	Description
items	ScrollSpyItem[]	required	Array of navigation items
position	'top'\|'left'\|'right'	'top'	Position of the navigation bar
offset	number	0	Offset in pixels from top for active section calculation
sticky	boolean	true	Enable sticky positioning
activeClass	string	''	Custom Tailwind classes for active items
class	string	''	Custom Tailwind classes for the nav container
smoothScroll	boolean	true	Enable smooth scroll behavior
onActiveChange	(id: string) => void	undefined	Callback when active section changes
onNavigate	(id: string) => void	undefined	Callback when navigation item is clicked

Accessibility

The ScrollSpy component is built with accessibility in mind:

✓ Keyboard Navigation: Navigation items are fully keyboard accessible using Tab and Enter/Space
✓ ARIA Support: Uses semantic HTML and aria-current for the active section
✓ Visible Focus State: Focus rings are preserved for keyboard users
✓ Screen Reader Friendly: Lists and links are announced correctly by assistive technology
✓ Color Contrast: Default styles follow WCAG AA contrast guidelines

Best Practices

• Use clear, descriptive labels for each navigation item
• Ensure sufficient color contrast if overriding default styles
• Test with keyboard-only navigation and screen readers
• Provide meaningful and properly structured section headings