# Anchor Tracks the current section on scroll and highlights it automatically; clicking an anchor smooth-scrolls to the target. Supports custom scroll containers, click landing offsets, multi-level nesting, horizontal direction, affix, a moving ink bar, style variants and history control. ## Basic usage `scroll-container` points to a local scroll container (selector or element id): both the observation root and the click landing target use it; when unset the viewport is used.

Chapter 1

Section 1 content: demonstrates scroll spy and highlight tracking.

Chapter 2

When scrolled into view, the anchor highlights the current section.

Chapter 3

Click an anchor to smooth-scroll to the corresponding section.

 ## Highlight offset and trigger boundary `offset` controls the highlight detection line (how early a section's top crosses the line); `bounds` is an extra lead for the trigger boundary (default 5) to avoid highlight flicker.

Chapter 1

offset controls the offset of the top highlight detection zone.

Chapter 2

The highlight switches earlier when a section top crosses the offset line.

Chapter 1

A larger bounds triggers the highlight switch earlier.

Chapter 2

Default is 5px; set to 40px here so the switch point difference is visible.

 ## Click events `oas-click` and `oas-change` are separate: **clicking** an anchor fires `oas-click` (`detail: { href, item }`); both clicks and **scroll-driven** highlight changes fire `oas-change` (`detail: { href, prevHref }`) — listen to `oas-click` when you want to react to user actions only.

Chapter 1

Click a left anchor: only oas-click fires. Scroll this container to switch highlights: only oas-change fires.

Chapter 2

oas-click carries the full item (href/title etc.).

Nothing clicked No oas-click yet ## Controlled highlight `active` is a controlled attribute: an external set/remove of `active` directly controls the currently highlighted item (the scroll spy still takes over as you scroll). Highlight Chapter 1 Highlight Chapter 2 Highlight Chapter 3 Clear highlight

Chapter 1

Click a left button to set active; the anchor highlights the corresponding item immediately.

Chapter 2

When scrolling this container, the scroll spy takes over highlighting.

Chapter 3

"Clear highlight" removes active, restoring the no-highlight state.

 ## Click landing offset and alignment `target-offset` controls the distance between the target and the container top after clicking (avoids fixed headers); it falls back to `offset` when unset. `block` controls the landing alignment (`start` / `center` / `end` / `nearest` — nearest does not scroll when the target is already fully visible, minimal scroll); `duration` controls the smooth scroll duration, while `animation="false"` or `duration="0"` jumps instantly.

Chapter 1

The dashed line marks the 80px landing line: after a click Chapter 1 aligns to it.

Chapter 2

duration=500 smooth-scrolls over about 500ms.

Chapter 1

block="center": the target section is vertically centered in the container.

Chapter 2

Click me to see the centered landing.

Chapter 1

block="nearest": no scroll at all when the target is already fully visible.

Click "Chapter 3" first to scroll to the bottom, then click "Chapter 1" — if Chapter 1 is already visible nothing scrolls (minimal scroll).

Chapter 2

A target below the container scrolls just enough for its bottom to appear.

Chapter 3

A target above the container scrolls just enough for its top to appear.

Chapter 1

animation="false": clicking jumps to the target instantly, no smooth transition.

Chapter 2

Equivalent to duration="0".

 ## Nesting and target markers `items` supports `children` for multi-level nesting (indented; child items take part in scroll highlighting). `` marks scroll targets component-style (its `id` is synced to the inner `part=target` element) instead of hand-writing heading ids. `internal-scrollable` makes the anchor list itself internally scrollable.

Chapter 1

Headings wrapped by oas-anchor-target serve as scroll landing targets.

1.1 Section

Child anchors are indented and take part in highlight detection.

1.2 Section

Child anchors are indented and take part in highlight detection.

1.3 Section

Child anchors are indented and take part in highlight detection.

1.4 Section

Child anchors are indented and take part in highlight detection.

1.5 Section

Child anchors are indented and take part in highlight detection.

Chapter 2

internal-scrollable: the anchor list scrolls internally when it overflows.

 ## Horizontal direction

Chapter 1

In horizontal mode the items are laid out in a row and the ink bar slides horizontally.

Chapter 2

Scroll the container to observe highlight switching.

Chapter 3

Clicking an anchor still lands on the section.

 ## Affix `affix` pins the anchor bar while scrolling (sticky positioning); `affix-offset` is the distance from the viewport top when affixed. This demo watches the viewport scroll.

Chapter 1

Scroll the page down: the left anchor bar sticks 16px below the viewport top.

Chapter 2

The highlight follows the current section as the page scrolls.

Chapter 3

Pair affix-offset with a fixed page header to clear it.

 ## Style variants and sizes

default

underline

lineless

block

size=small

size=large

 ## History control Clicking an anchor updates the URL hash by default (`history.pushState`); `replace` switches to `replaceState`; `hash="false"` writes nothing.

Chapter 1

Three anchors watch the same container: default pushState, replace via replaceState, and hash=false writes nothing.

Chapter 2

Click the first column's anchors to watch the URL hash change.

Nothing clicked ## Custom highlight `get-current-anchor` names a global function that receives the scroll-computed candidate href and returns the href to actually highlight; framework users can also pass a function via the `getCurrentAnchor` property.

Chapter 1

No matter where you scroll, the custom strategy forces Chapter 3 to be highlighted.

Chapter 2

The event detail.href also comes from the custom strategy.

Chapter 3

The actually highlighted item.

Not scrolled yet ## External links Setting `target` (e.g. `_blank`) on an item leaves the default behavior to the browser (with `rel="noopener noreferrer"` added automatically) and excludes it from scrolling/highlighting. ## Declarative child channel Besides the `items` JSON, you can write items declaratively with `` (the `items` attribute **wins when explicitly set**). The default slot text is the title; attributes map to the `AnchorItem` fields: `href`/`target`/`target-offset`; direct child `` elements recurse into `children` multi-level nesting (indented, and they participate in scroll highlighting too). Child additions/removals, attribute and text changes re-render automatically.
Chapter 1 Chapter 2

Chapter 1

Write anchor items declaratively with oas-anchor-item; scroll highlighting behaves the same as the items channel.

Chapter 2

Clicking an anchor scrolls smoothly to the target section.
Chapter 1 1.1 Sub-section 1.2 Sub-section Chapter 2

Chapter 1
1.1 Sub-section
1.2 Sub-section

Chapter 2

A per-item `target-offset` overrides the global landing offset; child items also participate in scroll highlighting.

Scroll to the bottom of this section and watch the left-side highlight follow.

Click "Chapter 2" on the left to smooth-scroll to this section.

Extra content to make the container overflow and scroll.

One more paragraph to ensure scrollability.

 ## API ### oas-anchor #### Attributes | Attribute | Description | Type | Default | | --- | --- | --- | --- | | `active` | Currently highlighted href (controlled: external set/remove takes effect immediately; the scroll spy writes it back) | `string` | — | | `affix` | Enable affix (sticky positioning, sticks to the scroll viewport/container) | `boolean` | — | | `affix-offset` | Distance from the scroll viewport top when affixed (px) | `string` | `0` | | `animation` | Smooth scroll switch (default true; `false` jumps instantly) | `string` | `true` | | `block` | Scroll landing alignment: `start` / `center` / `end` / `nearest` (does not scroll when the target is already fully visible — minimal scroll; aligns to top when above, to bottom when below) | `ScrollBlock` | `start` | | `bounds` | Trigger boundary (px, default 5): extra lead for a section's top crossing the detection line, avoids highlight flicker | `string` | `5` | | `direction` | Layout direction: `vertical` / `horizontal` | `string` | `vertical` | | `duration` | Smooth scroll duration in ms (default 300; `0` jumps instantly) | `string` | `300` | | `get-current-anchor` | Custom highlight strategy: attribute names a global function that receives the computed candidate href and returns the actual href to highlight; the `getCurrentAnchor` property also accepts a function | `((activeHref: string) => string) \| null` | — | | `hash` | Whether clicking updates the URL hash (default true; `false` disables) | `string` | `true` | | `internal-scrollable` | Make the anchor list itself internally scrollable (max-height + overflow-y: auto) | `boolean` | — | | `items` | Anchor items JSON; items support `children` (multi-level nesting), `target` (e.g. `_blank`) and per-item `targetOffset` | `AnchorItem[] \| string` | `[]` | | `offset` | Highlight detection offset in px: how early a section's top crosses the detection line | `string` | `0` | | `replace` | History control: use `history.replaceState` instead of pushState | `boolean` | — | | `scroll-container` | Scroll container selector or element id; when unset the viewport (window) is used | `HTMLElement \| string \| null` | — | | `size` | Size: `small` / `medium` / `large` | `string` | `medium` | | `target-offset` | Click landing offset in px (avoids fixed headers); falls back to `offset` when unset; per-item `targetOffset` wins | `string` | — | | `variant` | Style variant: `default` (rail + moving ink) / `underline` (sliding underline) / `lineless` (no axis) / `block` (filled background) | `string` | `default` | #### Events | Event | Description | | --- | --- | | `oas-change` | Fired on highlight change (both click and scroll-driven), `detail: { href, prevHref }` | | `oas-click` | Fired when a user clicks an anchor item (separate from the scroll-driven `oas-change`, so hosts can react to user actions only; also fires for external-link `target` items), `detail: { href, item }` | ### oas-anchor-target #### Attributes | Attribute | Description | Type | Default | | --- | --- | --- | --- | | `id` | Target marker id: synced to the inner `part=target` element, used by anchor items as the scroll landing target | — | — | #### Slots | Name | Description | | --- | --- | | default | The marked target content (e.g. multi-level headings) | ### oas-anchor-item #### Attributes | Attribute | Description | Type | Default | | --- | --- | --- | --- | | `href` | Anchor target: `#id` (or an external URL; combine with `target` for external links) | — | — | | `target` | Link target (e.g. `_blank`): when set, the default browser behavior is not intercepted (`rel="noopener noreferrer"` is added automatically) | — | — | | `target-offset` | Per-item click landing offset (px), overriding the global `target-offset`; invalid values are ignored | — | — | #### Slots | Name | Description | | --- | --- | | default | Anchor item title content (default slot text; direct `oas-anchor-item` children are excluded) | Scroll spy based on the scroll container (viewport by default); clicking smooth-scrolls to the target; `nav` + `aria-label="Anchor navigation"`, the current item has `aria-current="true"`. A target marker component: wraps real multi-level headings and serves as the scroll landing target for anchor items; the default slot carries the marked content.