Page Link Component - Router by Before Semicolon

`<page-link>`

The <page-link> component renders a standard HTML anchor (<a>) tag wrapper that intercepts click events, updates browser history, and highlights itself with an active attribute when matching the current location.

1<page-link path="/dashboard" title="Admin Panel">Go to Dashboard</page-link>

Attributes

Attribute	Type	Default	Description
`path`	`string`	Current Path	The destination pathname (e.g. `/home` or query-relative parameters).
`search`	`string`	`undefined`	Appends or updates search parameters (e.g. `tab=settings`).
`keep-current-search`	`boolean`	`false`	Retains existing URL search parameters when navigating to a new path.
`exact`	`boolean`	`true`	When `true`, links are marked active only on an exact pathname match.
`title`	`string`	`undefined`	The document title to set upon successful navigation.
`payload`	`object`	`{}`	History state payload. In HTML, provide a JSON-serialized object string.

Relative Path Resolution

To make page layout structures reusable, <page-link> automatically resolves shorthand prefixes:

No path attribute: Evaluates to the current browser pathname. Ideal when you only need to modify query parameters.
html
```
1<page-link search="filter=completed">Completed Tasks</page-link>
```

Dollar Prefix $: Replaced by the path of the closest parent <page-route> element in the DOM tree.

1<page-route path="/projects/:projectId">2    <!-- Resolves to: /projects/123/edit -->3    <page-link path="$/edit">Edit Project</page-link>4</page-route>

Tilde Prefix ~: Replaced by the current browser pathname. Useful for appending child sections.

1<!-- If current page is /profile -->2<!-- Resolves to: /profile/settings -->3<page-link path="~/settings">Settings</page-link>

Active State Styling

When the browser location matches the link's target, the component gains a native active attribute:

1<!-- Rendered active HTML element -->2<page-link path="/todos" active>Todos</page-link>

You can target this state in CSS using standard attributes or CSS shadow parts:

1/* Style the outer custom component element */2page-link[active] {3    font-weight: 700;4}5 6/* Style the inner anchor tag using shadow parts */7page-link::part(anchor) {8    color: var(--foreground);9    text-decoration: none;10    transition: border-color 0.2s;11}12 13page-link[active]::part(anchor) {14    border-bottom: 2px solid var(--primary);15    color: var(--primary);16}

Passing Payloads

Use payload to pass history state data to the next page.

In plain HTML, attributes are strings, so payload must be a valid JSON-serialized object:

1<page-link path="/dashboard" payload='{"role": "admin", "userId": 42}'>2    Enter Panel3</page-link>

When rendering <page-link> through Markup, pass the value as an object property:

1import { html } from '@beforesemicolon/web-component'2 3const user = { role: 'admin', userId: 42 }4 5html` <page-link path="/dashboard" payload="${user}"> Enter Panel </page-link> `

The payload is available on the destination route through getPageData(), onPage(), onPageChange(), or <page-data key="...">.

edit this doc