Anchor
Use Anchor for an “On this page” table of contents beside a long page, so readers see where they are and can jump to any section. For a narrow rail beside a long conversation, where the targets may not even be mounted, use Outline; to move between pages rather than within one, use Menu or PageNav.
- Each link’s
href(#id) must match theidof an element on the page: that element is what the anchor watches and scrolls to. - When the sections scroll inside an element instead of the window, pass that element as
offsetTarget; without it the anchor follows the window. AnchorLinkonly works insideAnchor.
Anchor is a table of contents that follows scrolling, like a page’s “On this page” outline. Each link points at an element by #id; the link whose target was scrolled to last is current and carries aria-current="location". Clicking a link scrolls its target into view (smoothly, unless the user prefers reduced motion) and puts its hash in the address bar without the browser’s jump.
#Demos
#Basic
Pass the links as an items tree. offsetTarget names the element that scrolls; without it the anchor follows the page. Once the panel can’t scroll further, the last section in view becomes current even though it never reaches the top.
Install
Add the package with your package manager.
Usage
Import the component and render it.
Props
Every prop has a default.
Events
Callbacks report what changed.
FAQ
Short answers to common questions.
#AnchorLink
The same outline by composition: nest AnchorLinks under Anchor.
Overview
Scroll the panel or click a link.
Setup
Scroll the panel or click a link.
Local
Scroll the panel or click a link.
Cloud
Scroll the panel or click a link.
Next steps
Scroll the panel or click a link.
#Rail and background
showRail draws the rail with a mark beside the current link; showBackground adds the tint behind it.
Colors
One section of a style guide.
Typography
One section of a style guide.
Spacing
One section of a style guide.
Motion
One section of a style guide.
#Block
type="block" drops the rail and highlights the current link as a block.
Account
Settings for this group.
Notifications
Settings for this group.
Settings for this group.
Push
Settings for this group.
Privacy
Settings for this group.
#Ignore gap
Here the targets are headings with space between them. By default a link is current only while its heading is at the top; with ignoreGap (left) the last heading passed stays current through the gap.
First
Second
Third
#Controlled
value sets the current link and onUpdateValue reports every change, from scrolling or a click.
Current: none
Plan
One stage of the release.
Build
One stage of the release.
Ship
One stage of the release.
Learn
One stage of the release.
#Anchor Props
| Name | Type | Default | Description | Version |
|---|---|---|---|---|
items | AnchorItem[] | undefined | The links as a tree. AnchorLink children render after them. | Unreleased |
value | string | null | undefined | The current link’s href. Setting it controls the anchor. | Unreleased |
defaultValue | string | null | null | Initial current link when uncontrolled. | Unreleased |
onUpdateValue | (value: string | null) => void | undefined | Called with the new current href, on scroll and on click. | Unreleased |
type | rail | block | rail | How the current link is marked. | Unreleased |
showRail | boolean | true | Draws the rail (rail type only). | Unreleased |
showBackground | boolean | true | Tints the current link (with the rail only). | Unreleased |
bound | number | 12 | How far below the container’s top, in px, a target counts as reached. Measured from the target’s scroll-margin-top, so a sticky header’s margin moves the line too. | Unreleased |
ignoreGap | boolean | false | Keeps the last reached link current between targets. | Unreleased |
offsetTarget | string | HTMLElement | Window | Document | RefObject | (() => HTMLElement | Window | Document | null) | window | The scroll container the targets live in: a selector, an element, a ref or a function. | Unreleased |
aria-label | string | locale Anchor.label | Names the nav landmark (“On this page”). | Unreleased |
#AnchorLink Props
| Name | Type | Default | Description | Version |
|---|---|---|---|---|
href | string | The target, as #id. | Unreleased | |
title | ReactNode | undefined | The link text. A string title is also the tooltip when it is cut off. | Unreleased |
children | ReactNode | undefined | Nested AnchorLinks. | Unreleased |
AnchorItem is { href: string; title: ReactNode; key?: Key; children?: AnchorItem[] }.
The current link can be controlled (value), and clicking replaces the hash instead of jumping, so the outline doesn’t add a history entry per click. To keep the anchor on screen, wrap it in a position: sticky element; to move to a link, set value or scroll the target yourself.