useScrollSpy

Collect headings from the DOM or title registry and track which section is currently visible, in the page or inside a nested scroll container (scrollHost).

Use the title registry to power a live-updating table of contents that highlights the section currently in view.

Loading demo…

import { ScrollView, View } from 'react-native'; import { Badge, Block, Row, Text, TitleRegistryProvider, useScrollSpy, useTitleRegistration } from '@plocks/ui'; const SECTIONS = [ { title: 'Overview', order: 1, copy: 'Introduce the feature and set expectations for what the rest of the document covers.' }, { title: 'Installation', order: 2, copy: 'List required packages and platform caveats so teams can get started quickly.' }, { title: 'Usage patterns', order: 3, copy: 'Highlight the most common ways to use the feature with short inline examples.' }, { title: 'Troubleshooting', order: 4, copy: 'Capture the top issues support sees and the fix steps that usually resolve them.' } ] as const; function Section({ title, order, copy }: { title: string; order: number; copy: string }) { const { elementRef, id } = useTitleRegistration({ text: title, order }); return ( <View ref={elementRef} nativeID={id}> <Text fw="semibold">{title}</Text> <Text size="sm" c="secondary">{copy}</Text> </View> ); } function TocList() { const { items, activeId } = useScrollSpy(); if (!items.length) { return <Text size="sm" c="muted">No headings detected yet.</Text>; } return ( <Row gap="xs" wrap="wrap"> {items.map(item => ( <Badge key={item.id} variant={activeId === item.id ? 'light' : 'outline'} c={activeId === item.id ? 'primary' : 'gray'} > {item.value} </Badge> ))} </Row> ); } export function Demo() { return ( <TitleRegistryProvider> <Block gap="lg"> <TocList /> <ScrollView style={{ maxHeight: 280 }} contentContainerStyle={{ gap: 24 }}> {SECTIONS.map(section => ( <Section key={section.title} {...section} /> ))} </ScrollView> </Block> </TitleRegistryProvider> ); }
Pass the scrolling element (or its ref) as scrollHost when the headings live inside a nested scroll container: it becomes the IntersectionObserver root and scroll listener target, and headings are looked up inside it when container is not given.

Loading demo…

import { useRef } from 'react'; import type { ScrollView } from 'react-native'; import { Block, Row, ScrollArea, TableOfContents, Text, Title, TitleRegistryProvider } from '@plocks/ui'; const SECTIONS = [ { id: 'overview', title: 'Overview', copy: 'Introduce the feature and set expectations for the rest of the document.' }, { id: 'install', title: 'Installation', copy: 'List required packages and platform caveats so teams can get started quickly.' }, { id: 'usage', title: 'Usage', copy: 'Highlight the most common ways to use the feature with short inline examples.' }, { id: 'theming', title: 'Theming', copy: 'Show which tokens the feature reads and how to override them per screen.' }, { id: 'troubleshooting', title: 'Troubleshooting', copy: 'Capture the top issues support sees and the steps that usually resolve them.' }, ]; export function Demo() { const hostRef = useRef<ScrollView>(null); return ( <TitleRegistryProvider> <Row gap="xl" align="flex-start"> <TableOfContents container="#scroll-spy-host-content" scrollSpyOptions={{ scrollHost: hostRef }} variant="outline" size="sm" p="sm" style={{ width: 200 }} /> <ScrollArea ref={hostRef} id="scroll-spy-host-content" h={240} grow={1} contentProps={{ gap: 'xl' }}> {SECTIONS.map(section => ( <Block key={section.id} gap="xs"> <Title order={2}>{section.title}</Title> <Text c="secondary">{section.copy}</Text> <Text c="secondary">{section.copy}</Text> </Block> ))} </ScrollArea> </Row> </TitleRegistryProvider> ); }