# Primary navigation
> A horizontal row of a website's main destinations with a current-page bar or pill, and a More disclosure that collects the trailing items that do not fit.
- ID: `cmp_primary_nav_01`
- Slug: `primary-nav-01`
- Version: `1.0.0` (current)
- Status: published
- Published: 2026-09-30
- Updated: 2026-09-30
- Available versions: `1.0.0`
- Kind: control
- Primary category: `navigation`
- Detail page: https://pagesugar.com/components/primary-nav-01?variant=neutral
- Preview: https://pagesugar.com/preview/primary-nav-01
## Variants
| Variant | Label | Default | Artifact digest |
| --- | --- | --- | --- |
| `neutral` | Neutral | yes | `sha256-d45b6be41f463f4695701af7b128662b1e840dd23d1379057defe55e026aa1bb` |
| `blue` | Blue | no | `sha256-57d787fff7f2f45e0fe98302e93c089211a2a2ba02e3469348f7eafadd35aee1` |
## Runtime and compatibility
- Runtime: svelte
- Svelte: 5
- SvelteKit required: no (portable Svelte component)
- Tailwind CSS: 4
- SSR: supported
- Requires client-side JavaScript: yes
- Integration level: local-interaction
- Appearance modes: light, dark
- Mode selection: Dark values apply when an ancestor has the class dark (for example \). Without that class the light values apply regardless of the system setting.
- Suggested directory: `src/lib/components/primary-nav-01`
## Dependencies
No third-party runtime packages.
## Services
No external services required.
## Usage
Pass the destinations in priority order and the current pathname. The row measures its own width after hydration and moves trailing items into More; before that, and with overflow off, it is a plain wrapping list. It does not read the router, render nested dropdowns or switch to a mobile drawer: the header around it decides those.
Required props: `items`
```svelte
Example
```
Limitations:
- The nav needs a width that does not depend on its content: a block element, or flex-1 with min-w-0 inside a flex row. Sized by its content, it has nothing to measure against.
- Until the component hydrates, and whenever overflow is off, items that do not fit wrap onto another row; the first measurement then collapses them into More, so a very long list shortens by a row as the page becomes interactive.
- Items leave the row from the end of the list only; put the destinations that must stay visible first.
- currentPath is compared as a pathname (query, hash and a trailing slash are ignored); absolute URLs never match. With prefix matching the root / only matches itself.
- Items with a blank label are skipped, since a link with no text has no accessible name.
- Renders nothing when items is empty.
- Dark colours apply inside an ancestor with the class dark; a media-query setup needs its own rule that sets the --primary-nav-\* variables.
## Usage guide
### Primary navigation
The main row of a site's destinations, for use inside a header you build yourself. It marks the
current page and, as the row narrows, moves the trailing items into a More disclosure so the row
never wraps or scrolls.
#### Placing it in a header
The nav measures its own width, so that width has to come from the layout, not from its links:
- On its own row (under the brand, as in the preview), it is a block and fills the row.
- Beside the brand in a flex row, wrap it so it takes the remaining width: `
`.
With the underline indicator the nav draws a hairline under itself and the current page's bar sits
on it. If your header already draws a bottom border, set `--primary-nav-hairline: transparent`
and put the nav flush against that border.
#### Current page
Pass the pathname (`page.url.pathname` in SvelteKit). Use `match="prefix"` when sections have
pages below them: `/blog` is then current for `/blog/planning-in-quarters`, with
`aria-current="true"` because the link is the section, not the page. The longest matching href
wins, so `/docs/api` beats `/docs` for `/docs/api/webhooks`.
If the current item has been collected into More, the More button carries the bar (or pill) and
announces `moreCurrentHint`, so the visitor is never left without a mark.
#### Before hydration
The server renders every item in a wrapping row, and so does the first client frame. Once the
component has hydrated it measures the labels (and measures again when a web font arrives or the
row resizes), then collects what does not fit. Put the destinations that must always be visible
first in `items`.
#### Small screens
The component does not switch to a drawer. At phone widths most items will be in More; if you
prefer a drawer, hide this nav below your breakpoint and show a drawer there instead.
## Props
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | `NavLink[]` | yes | | { label, href } destinations in priority order. Trailing items are the first to move into More. |
| `currentPath` | `string` | no | | Current URL pathname, for example page.url.pathname. The matching item gets aria-current and the current indicator. |
| `match` | 'exact' \| 'prefix' | no | `'exact'` | prefix also marks an item current for pages below it (/blog for /blog/a-post) with aria-current="true"; an exact match always gets aria-current="page". The longest matching href wins. |
| `indicator` | 'underline' \| 'pill' | no | `'underline'` | underline: a 2 px accent bar on the row's hairline. pill: an accent-filled pill and no hairline. |
| `overflow` | `boolean` | no | `true` | Collects the items that do not fit into a More disclosure. Off, the row wraps. |
| `moreLabel` | `string` | no | `'More'` | Text of the overflow button. |
| `moreCurrentHint` | `string` | no | `'includes the current page'` | Visually hidden suffix on the overflow button while the current page is inside it. Translate it with moreLabel. |
| `label` | `string` | no | `'Main'` | Accessible name of the nav landmark. |
## Customization
Change content through props, recolour through six --primary-nav-\* CSS variables on any ancestor, and switch the current-page mark with indicator.
- Colours: set --primary-nav-accent (the bar, the pill and the focus ring), --primary-nav-on-accent (text on the pill), --primary-nav-ink (current and hovered text), --primary-nav-muted (resting text), --primary-nav-hairline (the rule under the underline row) and --primary-nav-surface (the More panel). Hover, current and pressed fills are mixed from the ink.
- Dark or tinted header: for a zinc-950 band set --primary-nav-ink: #fafafa, --primary-nav-muted: #a1a1aa, --primary-nav-hairline: rgb(255 255 255 / 0.1), --primary-nav-surface: #18181b and --primary-nav-accent: #fafafa with --primary-nav-on-accent: #09090b.
- Hairline: set --primary-nav-hairline: transparent when the header draws its own bottom border, and place the nav flush with that border so the bar sits on it.
- Priority: order items by importance; the row keeps the leading items and collects from the end.
- Row height and density: the row is min-h-12 with min-h-8 links (min-h-14 rows and 44 px links under a coarse pointer), in PrimaryNav.svelte's itemClass and the ul.
- Panel: width and placement are the w-max, min-w-48 and max-w utilities on the More panel; it hangs from More's end edge, or from its start edge when that keeps it further inside the viewport, and re-places itself on resize while open.
- Overflow off: pass overflow={false} for a plain wrapping list with no measurement and no More button.
| Token | Public CSS variable |
| --- | --- |
| `accent` | `--primary-nav-accent` |
| `onAccent` | `--primary-nav-on-accent` |
| `ink` | `--primary-nav-ink` |
| `muted` | `--primary-nav-muted` |
| `hairline` | `--primary-nav-hairline` |
| `surface` | `--primary-nav-surface` |
## Accessibility
- One nav landmark named by label; give it a distinct name if the page has other nav regions.
- Each destination appears once in the accessibility tree: an item is either in the row or in the More panel, never both. The measuring copy of the labels is invisible, aria-hidden and inert.
- The exact match gets aria-current="page"; with prefix matching a section containing the page gets aria-current="true". The current item is marked by a 2 px bar (or a filled pill) and a heavier weight, not by colour alone.
- More follows the APG disclosure navigation pattern: a button with aria-expanded and aria-controls and a plain list of links, no menu roles. Enter or Space toggles it, Down Arrow opens it and enters the list, Up, Down, Home and End move between links, and Escape, focus leaving or a press outside closes it. Escape returns focus to More.
- When the current page is inside More, the button carries the current indicator and a visually hidden moreCurrentHint suffix; translate it with moreLabel.
- Focus is never dropped by a resize: a focused link collected into More hands focus to More, a focused panel link that returns to the row keeps focus there, and a focused More that disappears hands focus to the first item it held.
- Links and More show a 2 px focus outline in the accent colour with a 2 px offset; links grow to 44 px under a coarse pointer.
- IDs come from $props.id(), so two navs on one page keep distinct aria-controls targets.
Known limitations:
- Before hydration there is no More button; every item is in the wrapping list, so nothing is unreachable.
- Hover does not open More; it opens on click and keyboard only.
## License
- Declared source: MIT
- Default license approval is pending. See https://pagesugar.com/docs/license.
## Source
- Palette: Neutral (`neutral`)
- Entry: `PrimaryNav.svelte`
- Suggested directory: `src/lib/components/primary-nav-01`
- Files: 2
- Artifact digest: `sha256-d45b6be41f463f4695701af7b128662b1e840dd23d1379057defe55e026aa1bb`
Paths below are relative to the suggested directory. Copy the files as they are;
they import nothing from this site.
#### `PrimaryNav.svelte`
Role: entry · 15735 bytes · SHA-256 `122498aa2199341654951b7b0805114616e4ee87476b6bb1b3e44c412d3b2bb5`
```svelte
{#snippet labelText(text: string)}
{text}
{/snippet}
{#if items.length > 0}
{/if}
```
#### `types.ts`
Role: types · 1957 bytes · SHA-256 `2bd35972b01524c6c937198ecdb5e84424c0faeef6d836786eaf681f2ae2e575`
```ts
/** One top-level destination. */
export interface NavLink {
label: string;
href: string;
}
/** How currentPath is compared with each href. */
export type NavMatch = 'exact' | 'prefix';
/** What marks the current page in the row. */
export type NavIndicator = 'underline' | 'pill';
/** The aria-current value for a link: the page itself, a section containing it, or neither. */
export type CurrentState = 'page' | 'true' | undefined;
/** Pathname only: no query, no hash, no trailing slash (except the root). */
export const normalizePath = (path: string): string => {
const bare = path.split(/[?#]/, 1)[0];
return bare.length > 1 ? bare.replace(/\/+$/, '') : bare;
};
/**
* Index of the item that is current, or -1. An exact match always wins. With `prefix`, the
* item whose href is the longest leading segment of the path is current as a section, so
* `/blog` is current for `/blog/planning-in-quarters`; the root `/` only ever matches itself.
*/
export function currentIndex(
items: NavLink[],
currentPath: string | undefined,
match: NavMatch
): number {
if (!currentPath) return -1;
const path = normalizePath(currentPath);
const exact = items.findIndex((item) => normalizePath(item.href) === path);
if (exact !== -1 || match === 'exact') return exact;
let best = -1;
let bestLength = 0;
items.forEach((item, index) => {
const href = normalizePath(item.href);
if (href === '/' || !href.startsWith('/')) return;
if (path.startsWith(`${href}/`) && href.length > bestLength) {
best = index;
bestLength = href.length;
}
});
return best;
}
/** aria-current for the item at `index`, given the current index from currentIndex. */
export const currentState = (
items: NavLink[],
index: number,
current: number,
currentPath: string | undefined
): CurrentState => {
if (index !== current || !currentPath) return undefined;
return normalizePath(items[index].href) === normalizePath(currentPath) ? 'page' : 'true';
};
```
## Artifacts
### Neutral (`neutral`) (default)
- Artifact digest: `sha256-d45b6be41f463f4695701af7b128662b1e840dd23d1379057defe55e026aa1bb`
- Entry: `PrimaryNav.svelte`
- Receipt: https://pagesugar.com/artifacts/cmp_primary_nav_01/1.0.0/neutral/sha256-d45b6be41f463f4695701af7b128662b1e840dd23d1379057defe55e026aa1bb/manifest.json
- Bundle: https://pagesugar.com/artifacts/cmp_primary_nav_01/1.0.0/neutral/sha256-d45b6be41f463f4695701af7b128662b1e840dd23d1379057defe55e026aa1bb/bundle.zip (9697 bytes, sha256 `93556d813ac6c03f87baf84822632f82a42630a0a1acac3e132bb93792421b0e`)
Files:
- `PrimaryNav.svelte` (entry, 15735 bytes): https://pagesugar.com/artifacts/cmp_primary_nav_01/1.0.0/neutral/sha256-d45b6be41f463f4695701af7b128662b1e840dd23d1379057defe55e026aa1bb/source/PrimaryNav.svelte
- `types.ts` (types, 1957 bytes): https://pagesugar.com/artifacts/cmp_primary_nav_01/1.0.0/neutral/sha256-d45b6be41f463f4695701af7b128662b1e840dd23d1379057defe55e026aa1bb/source/types.ts