Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jpcutshall/svelte5-router/llms.txt

Use this file to discover all available pages before exploring further.

The Link component renders a standard HTML <a> element that performs client-side navigation without a full page reload. It resolves the to destination relative to the nearest Router base URI, listens for clicks, and calls the router’s navigate function instead of following the browser’s default anchor behaviour. Link automatically detects whether the rendered href matches the current pathname and sets aria-current="page" for accessibility. Because Link extends HTMLAnchorAttributes, every standard anchor attribute (class, id, data-*, etc.) is accepted and forwarded to the underlying <a> element.

​
Props

​
to
string
default:"#"
required
The destination URL. Absolute paths (starting with /) are used as-is. Relative paths are resolved against the nearest Router base URI using the same directory-style resolution that cd uses on a filesystem — every path is treated as a directory, never a file. If to is omitted entirely the link defaults to "#".
​
replace
boolean
default:"false"
When true, clicking the link calls history.replaceState instead of history.pushState, so the current URL is overwritten rather than a new entry being added. The router also implicitly replaces instead of pushing when the destination matches the current pathname, preventing duplicate history entries.
​
state
object
default:"{}"
An arbitrary serialisable object attached to the new history entry. Retrieve it later via useLocation() as location.state. Useful for passing ephemeral data between routes without exposing it in the URL.
​
preserveScroll
boolean
default:"false"
When true, the router will not call window.scrollTo(0, 0) after navigating to the linked route. Use this for in-page navigation (tabs, modals, anchor-linked sections) where restoring the scroll position to the top would be disorienting.
​
click
(e: MouseEvent) => void
An optional click-event handler called before the router’s own click logic. The handler receives the native MouseEvent. If you call event.preventDefault() inside this handler, the router will still inspect defaultPrevented and skip navigation accordingly.
​
children
Snippet<[boolean]>
required
Content rendered inside the <a> element. The snippet receives a single boolean argument — true when the link’s href exactly matches the current pathname (isCurrent), false otherwise. Use this to conditionally apply active styles or swap child components.
​
getProps
(params: GetPropsParams) => Record<string, any>
default:"() => ({})"
Deprecated. This prop is no longer applied to the rendered anchor element. The implementation still accepts the prop to avoid breaking existing code, but the returned object is currently ignored. Use the children active-state boolean or standard HTML attributes instead.
A callback that previously returned extra attributes to spread onto the <a> element. It received a GetPropsParams object with location, href, isPartiallyCurrent, and isCurrent fields.
​
...HTMLAnchorAttributes
HTMLAnchorAttributes
All remaining props are spread directly onto the underlying <a> element via Svelte’s rest-props mechanism. This includes class, id, style, target, rel, data-* attributes, and any other valid HTML anchor attribute — except href, which is always computed from to.

​
TypeScript Types

​
LinkProps

import type { Snippet } from "svelte";
import type { HTMLAnchorAttributes } from "svelte/elements";
import type { RouteLocation } from "svelte5-router";

type LinkProps = {
  /** Content snippet; receives `true` when this link is the active route. */
  children: Snippet<[boolean]>;
  /** Destination URL. */
  to: string;
  /** Replace history entry instead of pushing. Default: false. */
  replace?: boolean;
  /** Prevent scroll-to-top on navigation. Default: false. */
  preserveScroll?: boolean;
  /** State object pushed to the history entry. Default: {}. */
  state?: {
    [k in string | number]: unknown;
  };
  /** @deprecated No longer applied to the anchor element. */
  getProps?: (linkParams: GetPropsParams) => Record<string, any>;
  /** Click event handler called before router navigation logic. */
  click?: (e: MouseEvent) => void;
} & Omit<HTMLAnchorAttributes, "href" | "children">;

​
GetPropsParams

Passed to the deprecated getProps callback. Documented here for completeness. 
type GetPropsParams = {
  /** The current browser location. */
  location: RouteLocation;
  /** The fully resolved href of this Link. */
  href: string;
  /** True when the current pathname starts with href. */
  isPartiallyCurrent: boolean;
  /** True when the current pathname equals href exactly. */
  isCurrent: boolean;
};

​
aria-current Behaviour

Link sets aria-current="page" on the rendered <a> element whenever the resolved href exactly equals location.pathname. When the link is not current the attribute is omitted entirely (set to undefined). This keeps the DOM clean and works correctly with screen readers and CSS attribute selectors: 
/* Style the active link with a CSS attribute selector */
a[aria-current="page"] {
  font-weight: bold;
  text-decoration: underline;
}

​
Examples

<script>
  import { Router, Link, Route } from "svelte5-router";
  import Home from "./routes/Home.svelte";
  import About from "./routes/About.svelte";
</script>

<Router>
  <nav>
    <Link to="/">
      {#snippet children()}
        Home
      {/snippet}
    </Link>
    <Link to="/about">
      {#snippet children()}
        About
      {/snippet}
    </Link>
  </nav>

  <Route path="/" component={Home} />
  <Route path="/about" component={About} />
</Router>

Build docs developers (and LLMs) love

Get started for freeTalk to us