SectionJumper

Quick Preview

Usage

SectionJumper supports two sources: explicit items inside ScrollSpy, or headings discovered automatically by SectionJumperProvider. Use the provider for blog and CMS markup where headings should remain ordinary HTML.

import { SectionJumper } from "@giddaa-housing/ui/section-jumper";
import {
  ScrollSpy,
  ScrollSpyContent,
} from "@giddaa-housing/ui/scroll-spy";

const sections = [
  { value: "overview", label: "Overview" },
  { value: "gallery", label: "Gallery" },
  { value: "amenities", label: "Amenities" },
];

export function PropertyDetails() {
  return (
    <ScrollSpy defaultValue="overview" scrollOffset={72}>
      <SectionJumper
        items={sections}
        className="sticky top-20 z-20 ml-auto"
      />

      {sections.map((section) => (
        <ScrollSpyContent key={section.value} value={section.value}>
          <h2>{section.label}</h2>
        </ScrollSpyContent>
      ))}
    </ScrollSpy>
  );
}

When it is rendered inside ScrollSpy, every item should have a matching ScrollSpyContent.

Examples

Responsive behavior

On desktop, the resting control is a vertical indicator rail. Hovering or activating the rail opens the labelled menu in a popover. On mobile, it becomes a horizontal indicator chip showing the current section; activating it opens the same popover primitive with a wider, touch-friendly menu. The chip never grows past the viewport — the dots hold their size and the label gives up the remaining room.

The default breakpoint is 1024px. Change mobileBreakpoint when the surrounding layout switches earlier or later.

Long pages

An article can have more sections than a rail can usefully draw, and labels longer than a fixed-width menu can hold. Both are handled without configuration:

• The rail windows. Past maxDots sections it draws a sliding window of dots centred on the current one, pinned at either end so the first and last sections stay reachable. The dots at an end the window hasn't reached yet are drawn smaller, so it reads as "there is more this way". Defaults to 12 dots on desktop and 7 on mobile, where they share a row with the section label.
• The menu scrolls. The popover stops at whatever room it has on screen — it never runs off the bottom — and the section list inside it scrolls, with the heading pinned. It opens with the current section already in view.
• The menu sizes to its labels. On desktop the panel grows with the longest label between 240px and 320px instead of truncating everything to a fixed width. On mobile it stays a full-width sheet-like panel, clamped to the viewport.

The menu always lists every section — maxDots only affects the resting rail.

Blog and CMS content

For CMS article markup, wrap the jumper and article in SectionJumperProvider. The provider discovers headings, uses their text as labels, and generates IDs when the CMS did not provide them. No item array or ScrollSpyContent wrappers are required.

<SectionJumperProvider selectors={["h2", "h3"]} scrollOffset={80}>
  <SectionJumper />
  <article>
    <h2>Introduction</h2>
    <p>...</p>
    <h2>Financing</h2>
    <h3>Mortgage options</h3>
  </article>
</SectionJumperProvider>;

The default selector is h2. Pass any selector array needed by the article structure, such as selectors={["h2", "h3"]}. Empty headings are ignored. Discovery reruns when CMS content changes, and the nearest vertical scrolling container is tracked automatically.

Controlled open state

Use open and onOpenChange when another control or application event needs to coordinate with the popover. For ordinary use, omit them and optionally seed the component with defaultOpen.

const [open, setOpen] = useState(false);

<SectionJumper
  items={sections}
  open={open}
  onOpenChange={setOpen}
/>;

Selecting a section closes the popover after delegating the jump to ScrollSpy.

Props

SectionJumperProvider props

Accessibility

• The trigger announces the current section on desktop.
• The active menu item uses aria-current="location" as well as visual styling.
• Menu buttons reference their matching content regions with aria-controls.
• The underlying Popover manages focus, dismissal, and keyboard interaction.
• Section changes retain ScrollSpy's reduced-motion behavior and focus handoff.

Guidance

• Use it for navigation within one long page, not for moving between routes.
• Keep exactly one section active and keep item order aligned with document order.
• Prefer short labels that remain recognizable in the compact mobile trigger.
• Position the jumper with sticky or fixed in the consuming layout; the component deliberately does not impose page positioning.