Domet

$3

Domet is a lightweight React hook built for scroll-driven interfaces. Use it for classic scroll-spy, but also for progress indicators, lazy section loading, or any UI that needs reliable section awareness.

Lightweight under the hood: a tight scroll loop and hysteresis for stable, flicker-free section tracking.

For the source code, check out the GitHub.

$3

Install the package from your command line. Requires React 18 or 19.

``bash
npm install domet
`

$3

Basic example of how to use the hook.

`tsx showLineNumbers
import { useDomet } from 'domet'

const ids = ['intro', 'features', 'api']

function Page() {
const { active, register, link } = useDomet({
ids,
})

return (
<>


...

...

...

)
}
`

$3

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| ids | string[] | — | Array of section IDs to track (mutually exclusive with selector) |
| selector | string | — | CSS selector to find sections (mutually exclusive with ids) |
| container | RefObject | undefined | React ref to scrollable container (defaults to window) |
| tracking | TrackingOptions | undefined | Tracking configuration (offset, threshold, hysteresis, throttle) |
| scrolling | ScrollingOptions | undefined | Default scroll behavior for link/scrollTo (behavior, offset, position, lockActive) |

tracking.offset and scrolling.offset serve different purposes:
- tracking.offset: Defines the trigger line position (where section detection happens). A value of 100 means the line sits 100px from the top of the viewport. Sections crossing this line are candidates for "active".
- scrolling.offset: Only affects programmatic scrolling (link/scrollTo). It shifts where the section lands after navigation. Has no effect on detection.

Tracking defaults are threshold: 0.6, hysteresis: 150, and throttle: 10 (ms). scrolling.behavior defaults to auto, which resolves to smooth unless prefers-reduced-motion is enabled (then instant).

IDs are sanitized: non-strings, empty values, and duplicates are ignored. Passing both ids and selector logs a warning in development; selector is ignored.

$3

| Prop | Type | Description |
|------|------|-------------|
| onActive | (id: string \| null, prevId: string \| null) => void | Called when active section changes |
| onEnter | (id: string) => void | Called when a section enters the viewport |
| onLeave | (id: string) => void | Called when a section leaves the viewport |
| onScrollStart | () => void | Called when scrolling starts |
| onScrollEnd | () => void | Called when scrolling stops |

Callbacks do not fire while lockActive is enabled during programmatic scroll. onScrollEnd fires after 100 ms of scroll inactivity.

$3

| Prop | Type | Description |
|------|------|-------------|
| active | string \| null | ID of the currently active section |
| index | number | Index of the active section in ids (-1 if none) |
| progress | number | Overall scroll progress (0-1), shortcut for scroll.progress |
| direction | 'up' \| 'down' \| null | Scroll direction, shortcut for scroll.direction |
| ids | string[] | Resolved section IDs (useful with CSS selector) |
| scroll | ScrollState | Full scroll state object |
| sections | Record | Per-section state indexed by ID |
| register | (id: string) => RegisterProps | Props to spread on section elements (includes id, ref, data-domet) |
| link | (id: string, options?: ScrollToOptions) => LinkProps | Nav props (onClick, aria-current, data-active) with optional scroll overrides |
| navRef | (id: string, options?: NavRefOptions) => (el: HTMLElement \| null) => void | Ref callback for nav items; auto-scrolls active item into view in scrollable nav containers |
| scrollTo | (target: ScrollTarget, options?: ScrollToOptions) => void | Programmatically scroll to a section or absolute scroll position |

$3

$3

Options that control tracking behavior.

`ts showLineNumbers
type TrackingOptions = {
offset?: number | ${number}%
threshold?: number
hysteresis?: number
throttle?: number
}
`

Defaults: threshold: 0.6, hysteresis: 150, throttle: 10 (ms).

$3

Defaults for programmatic scrolling (link/scrollTo).

`ts showLineNumbers
type ScrollingOptions = {
behavior?: 'smooth' | 'instant' | 'auto'
offset?: number | ${number}%
position?: 'top' | 'center' | 'bottom'
lockActive?: boolean
}
`

If position is omitted for ID targets, Domet uses a dynamic alignment that keeps the trigger line within the section and prefers centering sections that fit in the viewport. When position: "center" is set, sections that fit in the viewport are centered; sections taller than the viewport align to the top instead (respecting scrolling.offset).

$3

Options for customizing nav item auto-scrolling behavior.

`ts showLineNumbers
type NavRefOptions = {
behavior?: 'smooth' | 'instant' | 'auto'
offset?: number
position?: 'nearest' | 'center' | 'start' | 'end'
}
`

- behavior: Scroll animation ('auto' respects prefers-reduced-motion). Default: 'auto'.
- offset: Pixel offset from container edge when scrolling nav items. Default: 0.
- position: Alignment within the scrollable container. Default: 'nearest'.

$3

Global scroll information updated on every scroll event.

`ts showLineNumbers
type ScrollState = {
y: number // Current scroll position in pixels
progress: number // Overall scroll progress (0-1)
direction: 'up' | 'down' | null // Scroll direction
velocity: number // Scroll speed
scrolling: boolean // True while actively scrolling
maxScroll: number // Maximum scroll value
viewportHeight: number // Viewport height in pixels
trackingOffset: number // Effective tracking offset
triggerLine: number // Dynamic trigger line position in viewport
}
`

$3

Per-section state available for each tracked section. visibility and progress are rounded to 2 decimals.

`ts showLineNumbers
type SectionState = {
bounds: SectionBounds // Position and dimensions
visibility: number // Visibility ratio (0-1)
progress: number // Section scroll progress (0-1)
inView: boolean // True if any part is visible
active: boolean // True if this is the active section
rect: DOMRect | null // Full bounding rect
}

type SectionBounds = {
top: number
bottom: number
height: number
}
`

$3

Target input for programmatic scrolling.

`ts showLineNumbers
type ScrollTarget =
| string
| { id: string }
| { top: number } // Absolute scroll position in px (scrolling.offset is subtracted)
`

$3

Options for programmatic scrolling. Use scrolling in the hook options for defaults, and pass overrides to link or scrollTo.

`ts showLineNumbers
type ScrollToOptions = {
offset?: number | ${number}% // Override scroll target offset (applies to id/top targets)
behavior?: 'smooth' | 'instant' | 'auto' // Override scroll behavior
position?: 'top' | 'center' | 'bottom' // Section alignment for ID targets only
lockActive?: boolean // Lock active section during programmatic scroll
}
`

By default, lockActive is enabled for id targets and disabled for { top }.

$3

$3

React to section changes with callbacks for analytics, animations, or state updates:

`tsx showLineNumbers
const { active } = useDomet({
ids: ['intro', 'features', 'api'],
onActive: (id, prevId) => {
console.log(Changed from ${prevId} to ${id})
},
onEnter: (id) => {
console.log(Entered: ${id})
},
})
`

$3

Build progress indicators and scroll-driven animations using the scroll state:

`tsx showLineNumbers
const { progress, sections, ids } = useDomet({
ids: ['intro', 'features', 'api'],
})

// Global progress bar