Anchor
Scroll-aware table-of-contents navigation. Provide items manually or point it at a scrollable container to auto-discover headings.
import { Anchor } from "phoundry-ui";Basic (Manual Items)
Loading interactive example…
View source
<script lang="ts"> import { Anchor } from "phoundry-ui"; import type { AnchorItem } from "phoundry-ui";
let manualContainer = $state<HTMLElement>();
const basicItems: AnchorItem[] = [ { key: "basic-intro", href: "#basic-intro", title: "Introduction" }, { key: "basic-install", href: "#basic-install", title: "Installation" }, { key: "basic-usage", href: "#basic-usage", title: "Usage" }, { key: "basic-api", href: "#basic-api", title: "API Reference" }, ];</script>
<div class="flex gap-4"> <Anchor items={basicItems} target={manualContainer} affix={false} /> <div bind:this={manualContainer} class="h-48 flex-1 space-y-4 overflow-y-auto rounded-lg border border-border-muted p-4" > <section id="basic-intro"> <h3 class="text-sm font-medium text-txt-primary">Introduction</h3> <p class="mt-1 text-xs text-txt-secondary"> Welcome to the Anchor component. It provides scroll-aware navigation for long pages. </p> <div class="h-24"></div> </section> <section id="basic-install"> <h3 class="text-sm font-medium text-txt-primary">Installation</h3> <p class="mt-1 text-xs text-txt-secondary"> Install via npm: <code>npm install phoundry-ui</code> </p> <div class="h-24"></div> </section> <section id="basic-usage"> <h3 class="text-sm font-medium text-txt-primary">Usage</h3> <p class="mt-1 text-xs text-txt-secondary"> Import the component and pass your items array. </p> <div class="h-24"></div> </section> <section id="basic-api"> <h3 class="text-sm font-medium text-txt-primary">API Reference</h3> <p class="mt-1 text-xs text-txt-secondary"> See the props table below for full API documentation. </p> <div class="h-24"></div> </section> </div></div>Auto-Discovery
Loading interactive example…
View source
<script lang="ts"> import { Anchor } from "phoundry-ui";
let autoContainer = $state<HTMLElement>();</script>
<div class="flex gap-4"> <Anchor target={autoContainer} headingSelector="h3" affix={false} /> <div bind:this={autoContainer} class="h-48 flex-1 space-y-4 overflow-y-auto rounded-lg border border-border-muted p-4" > <section> <h3 class="text-sm font-medium text-txt-primary">Overview</h3> <p class="mt-1 text-xs text-txt-secondary"> The auto mode scans the container for headings and builds the item list. </p> <div class="h-24"></div> </section> <section> <h3 class="text-sm font-medium text-txt-primary">Configuration</h3> <p class="mt-1 text-xs text-txt-secondary"> Use headingSelector to control which elements are picked up. </p> <div class="h-24"></div> </section> <section> <h3 class="text-sm font-medium text-txt-primary">Scroll Tracking</h3> <p class="mt-1 text-xs text-txt-secondary"> Active state updates automatically as the user scrolls. </p> <div class="h-24"></div> </section> <section> <h3 class="text-sm font-medium text-txt-primary">Events</h3> <p class="mt-1 text-xs text-txt-secondary"> onChange fires whenever the active link changes. </p> <div class="h-24"></div> </section> </div></div>Horizontal
Loading interactive example…
View source
<script lang="ts"> import { Anchor } from "phoundry-ui"; import type { AnchorItem } from "phoundry-ui";
let horizontalContainer = $state<HTMLElement>();
const basicItems: AnchorItem[] = [ { key: "basic-intro", href: "#basic-intro", title: "Introduction" }, { key: "basic-install", href: "#basic-install", title: "Installation" }, { key: "basic-usage", href: "#basic-usage", title: "Usage" }, { key: "basic-api", href: "#basic-api", title: "API Reference" }, ];</script>
<div class="space-y-2"> <Anchor items={basicItems.map((i) => ({ ...i, key: "hz-" + i.key, href: "#hz-" + i.key.replace("basic-", ""), }))} target={horizontalContainer} direction="horizontal" affix={false} /> <div bind:this={horizontalContainer} class="h-36 space-y-4 overflow-y-auto rounded-lg border border-border-muted p-4" > <section id="hz-intro"> <h3 class="text-sm font-medium text-txt-primary">Introduction</h3> <p class="mt-1 text-xs text-txt-secondary"> Horizontal anchor for compact navigation. </p> <div class="h-20"></div> </section> <section id="hz-install"> <h3 class="text-sm font-medium text-txt-primary">Installation</h3> <p class="mt-1 text-xs text-txt-secondary">Same install process.</p> <div class="h-20"></div> </section> <section id="hz-usage"> <h3 class="text-sm font-medium text-txt-primary">Usage</h3> <p class="mt-1 text-xs text-txt-secondary"> Set direction to horizontal. </p> <div class="h-20"></div> </section> <section id="hz-api"> <h3 class="text-sm font-medium text-txt-primary">API Reference</h3> <p class="mt-1 text-xs text-txt-secondary">Full API below.</p> <div class="h-20"></div> </section> </div></div>Nested Items
Loading interactive example…
View source
<script lang="ts"> import { Anchor } from "phoundry-ui"; import type { AnchorItem } from "phoundry-ui";
let nestedContainer = $state<HTMLElement>();
const nestedItems: AnchorItem[] = [ { key: "nested-getting-started", href: "#nested-getting-started", title: "Getting Started", children: [ { key: "nested-prereqs", href: "#nested-prereqs", title: "Prerequisites", }, { key: "nested-setup", href: "#nested-setup", title: "Setup" }, ], }, { key: "nested-components", href: "#nested-components", title: "Components", children: [ { key: "nested-button", href: "#nested-button", title: "Button" }, { key: "nested-input", href: "#nested-input", title: "Input" }, { key: "nested-select", href: "#nested-select", title: "Select" }, ], }, ];</script>
<div class="flex gap-4"> <Anchor items={nestedItems} target={nestedContainer} affix={false} /> <div bind:this={nestedContainer} class="h-56 flex-1 space-y-4 overflow-y-auto rounded-lg border border-border-muted p-4" > <section id="nested-getting-started"> <h2 class="text-sm font-semibold text-txt-primary">Getting Started</h2> <div class="h-12"></div> </section> <section id="nested-prereqs"> <h3 class="pl-2 text-xs font-medium text-txt-primary">Prerequisites</h3> <p class="mt-1 pl-2 text-xs text-txt-secondary">Node.js 18+, Svelte 5.</p> <div class="h-16"></div> </section> <section id="nested-setup"> <h3 class="pl-2 text-xs font-medium text-txt-primary">Setup</h3> <p class="mt-1 pl-2 text-xs text-txt-secondary">Run the init script.</p> <div class="h-16"></div> </section> <section id="nested-components"> <h2 class="text-sm font-semibold text-txt-primary">Components</h2> <div class="h-12"></div> </section> <section id="nested-button"> <h3 class="pl-2 text-xs font-medium text-txt-primary">Button</h3> <p class="mt-1 pl-2 text-xs text-txt-secondary"> Primary action trigger. </p> <div class="h-16"></div> </section> <section id="nested-input"> <h3 class="pl-2 text-xs font-medium text-txt-primary">Input</h3> <p class="mt-1 pl-2 text-xs text-txt-secondary">Text input field.</p> <div class="h-16"></div> </section> <section id="nested-select"> <h3 class="pl-2 text-xs font-medium text-txt-primary">Select</h3> <p class="mt-1 pl-2 text-xs text-txt-secondary">Dropdown selector.</p> <div class="h-16"></div> </section> </div></div>Offsets, replaceState, onChange
Loading interactive example…
View source
<script lang="ts"> import { Anchor } from "phoundry-ui"; import type { AnchorItem } from "phoundry-ui";
let offsetContainer = $state<HTMLElement>();
let activeHash = $state("");
const basicItems: AnchorItem[] = [ { key: "basic-intro", href: "#basic-intro", title: "Introduction" }, { key: "basic-install", href: "#basic-install", title: "Installation" }, { key: "basic-usage", href: "#basic-usage", title: "Usage" }, { key: "basic-api", href: "#basic-api", title: "API Reference" }, ];</script>
<p class="mb-2 text-xs text-txt-secondary"> <code>offsetTop</code> shifts which heading counts as “active” while scrolling. <code>targetOffset</code> controls the gap after clicking (defaults to <code>offsetTop</code>). <code>replace</code> avoids cluttering history on each jump.</p><div class="flex gap-4"> <Anchor items={basicItems.map((i) => ({ ...i, key: "off-" + i.key, href: "#off-" + i.key.replace("basic-", ""), }))} target={offsetContainer} offsetTop={28} targetOffset={12} replace affix={false} onChange={(href) => { activeHash = href; }} /> <div bind:this={offsetContainer} class="h-44 flex-1 space-y-4 overflow-y-auto rounded-lg border border-border-muted p-4" > <section id="off-intro"> <h3 class="text-sm font-medium text-txt-primary">Introduction</h3> <p class="mt-1 text-xs text-txt-secondary"> Scroll to see <code>onChange</code> update. </p> <div class="h-20"></div> </section> <section id="off-install"> <h3 class="text-sm font-medium text-txt-primary">Installation</h3> <p class="mt-1 text-xs text-txt-secondary">Middle segment.</p> <div class="h-20"></div> </section> <section id="off-usage"> <h3 class="text-sm font-medium text-txt-primary">Usage</h3> <p class="mt-1 text-xs text-txt-secondary">Another section.</p> <div class="h-20"></div> </section> <section id="off-api"> <h3 class="text-sm font-medium text-txt-primary">API Reference</h3> <p class="mt-1 text-xs text-txt-secondary">Last segment.</p> <div class="h-20"></div> </section> </div></div>{#if activeHash} <p class="mt-2 text-[11px] text-txt-tertiary"> Active: <code>{activeHash}</code> </p>{/if}API
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
items | AnchorItem[] | — | Explicit anchor items (manual mode). |
target | HTMLElement | — | Scrollable container to scan for headings (auto mode). |
headingSelector | string | 'h2, h3' | CSS selector for discoverable headings in auto mode. |
direction | "horizontal" | "vertical" | 'vertical' | Layout direction. Horizontal disables nesting. |
offsetTop | number | 0 | Pixel offset for calculating the active section position. |
targetOffset | number | — | Scroll-to offset when clicking a link. Defaults to offsetTop. |
bounds | number | 5 | Bounding distance in px for active section detection. |
affix | boolean | true | Stick the anchor with position: sticky. |
replace | boolean | false | Use replaceState instead of pushState for URL hash. |
onChange | (activeHref: string) => void | — | Fires when the highlighted link changes (hash string, e.g. #section-id). |
onclick | (e: MouseEvent, item: AnchorItem) => void | — | Click handler for anchor links. |
getCurrentAnchor | (activeHref: string) => string | — | Override which link is highlighted. |
class | string | '' | Additional CSS classes. |
AnchorItem
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
keyrequired | string | — | Unique identifier. |
hrefrequired | string | — | Hash target (e.g. #section-id). |
titlerequired | string | — | Display text. |
children | AnchorItem[] | — | Nested child links (vertical only). |
Usage tips
- Pass
itemsfor full control, ortargetto auto-discover headings from a container. - In auto mode, headings without
idattributes get one assigned automatically (slugified from text). - Use
headingSelectorto control which heading levels are included (e.g."h2, h3"or just"h3"). - Set
direction="horizontal"for compact inline navigation. Nesting is disabled in horizontal mode. - The component renders nothing when there are no items - safe to include in layouts unconditionally.
- Add to a layout file with
target={mainEl}to get a page ToC on every page automatically.
CSS styling
.ph-anchor is the stable identification hook for Anchor. Part selectors and --_ph-* properties are internal. Component CSS is scoped and unlayered; Consumer classes remain additive and utility overrides may lose precedence.
Scroll tracking and measured ink-indicator geometry are unchanged. Direction and active-link styling are represented by attributes.
Keep the shared component stylesheet and a named Theme imported. Decorative motion respects reduced-motion preferences.
Anchor scrolling is immediate when reduced motion is requested; otherwise it remains smooth.