svelte5-router
v3.0.1
Published
A declarative Svelte routing library with SSR support
Downloads
107
Maintainers
Readme
Svelte5 Router
Forked from svelte-routing
A declarative Svelte routing library with SSR support.
Install
npm i -D svelte5-router
Usage
<!-- App.svelte -->
<script>
import { Router, Link, Route } from "svelte5-router";
import Home from "./routes/Home.svelte";
import About from "./routes/About.svelte";
import Blog from "./routes/Blog.svelte";
export let url = "";
</script>
<Router {url}>
<nav>
<Link to="/">Home</Link>
<Link to="/about">About</Link>
<Link to="/blog">Blog</Link>
</nav>
<div>
<Route path="/blog/:id" component={BlogPost} />
<Route path="/blog" component={Blog} />
<Route path="/about" component={About} />
<Route path="/"><Home /></Route>
</div>
</Router>
// main.js
import App from "./App.svelte";
import { mount } from "svelte";
const app = mount(App, {
target: document.getElementById("app"),
});
API
Router
The Router
component supplies the Link
and Route
descendant components
with routing information through context, so you need at least one Router
at
the top of your application. It assigns a score to all its Route
descendants
and picks the best match to render.
Router
components can also be nested to allow for seamless merging of many
smaller apps.
Properties
| Property | Required | Default Value | Description |
| :--------------: | :------: | :-----------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| basepath
| | "/"
| The basepath
property will be added to all the to
properties of Link
descendants and to all path
properties of Route
descendants. This property can be ignored in most cases, but if you host your application on e.g. https://example.com/my-site
, the basepath
should be set to /my-site
. |
| url
| | ""
| The url
property is used in SSR to force the current URL of the application and will be used by all Link
and Route
descendants. A falsy value will be ignored by the Router
, so it's enough to declare let url = $state("");
for your topmost component and only give it a value in SSR. |
| viewtransition
| | null
| View Transition (Experimental) |
Link
A component used to navigate around the application.
Properties
| Property | Required | Default Value | Description |
| :--------------: | :------: | :-----------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| to
| ✔ ️ | "#"
| URL the component should link to. |
| replace
| | false
| When true
, clicking the Link
will replace the current entry in the history stack instead of adding a new one. |
| state
| | {}
| An object that will be pushed to the history stack when the Link
is clicked. |
| ~~getProps
~~ | | () => ({})
| A function that returns an object that will be spread on the underlying anchor element's attributes. The first argument given to the function is an object with the properties location
, href
, isPartiallyCurrent
, isCurrent
. |
| preserveScroll
| | false
| When true
, clicking the Link
will not scroll the page to the top. |
Route
A component that will render its component
property or children when its
ancestor Router
component decides it is the best match.
All properties other than path
and component
given to the Route
will be
passed to the rendered component
.
Potential path parameters will be passed to the rendered component
as
properties. A wildcard *
can be given a name with *wildcardName
to pass the
wildcard string as the wildcardName
property instead of as the *
property.
Potential path parameters are passed back to the parent using props, so they can be exposed to the children snippet.
<Route path="/blog/:id">
{#snippet children(params)}
<BlogPost id="{params.id}" />
{/snippet}
</Route>
The active status of link can be exposed to the children snippet.
<Link to="/browser">
{#snippet children(active)}
<MenuItem active={active}>Browser</MenuItem>
{/snippet}
</Link>
Properties
| Property | Required | Default Value | Description |
| :-------------: | :------: | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| path
| | ""
| The path for when this component should be rendered. If no path
is given the Route
will act as the default that matches if no other Route
in the Router
matches. |
| ~~component
~~ | | null
| The component constructor that will be used for rendering when the Route
matches. If component
is not set, the children of Route
will be rendered instead. |
| children
| yes | | children passed inside the element. You can use the children snippet to access any url parameters {#snippet children(params)}
|
navigate
A function that allows you to imperatively navigate around the application for
those use cases where a Link
component is not suitable, e.g. after submitting
a form.
The first argument is a string denoting where to navigate to, and the second
argument is an object with a replace
, state
and preserveScroll
properties equivalent to those
in the Link
component.
<script>
import { navigate } from "svelte5-router";
function onSubmit() {
login().then(() => {
navigate("/success", { replace: true });
});
}
</script>
link
An action used on anchor tags to navigate around the application. You can add an
attribute replace
to replace the current entry in the history stack instead of
adding a new one and preserveScroll
to not scroll the page to the top when clicked.
<script>
import { link } from "svelte5-router";
</script>
<Router>
<a href="/" use:link>Home</a>
<a href="/replace" use:link replace>Replace this URL</a>
<!-- ... -->
</Router>
links
An action used on a root element to make all relative anchor elements navigate
around the application. You can add an attribute replace
on any anchor to
replace the current entry in the history stack instead of adding a new one.
You can add an attribute preserveScroll
on any anchor to not to scroll the page to the top when clicked. You
can add an attribute noroute
for this action to skip over the anchor and allow
it to use the native browser action.
<!-- App.svelte -->
<script>
import { links } from "svelte5-router";
</script>
<div use:links>
<Router>
<a href="/">Home</a>
<a href="/replace" replace>Replace this URL</a>
<a href="/native" noroute>Use the native action</a>
<!-- ... -->
</Router>
</div>
viewtransition
Viewtransition for navigation (Experimental).
builtin transition
<script>
import { fade } from "svelte/transition";
// ...
</script>
<Router viewtransition="{() => { fn: fade, duration: 500 }}">
<Route path="/" component="{Home}" />
<Route path="/contact" component="{Contact}" />
</Router>
custom transition
<script>
import { cubicin } from "svelte/easing";
// ...
</script>
<Router
viewtransition="{() => { duration: 500, easing: cubicin, css: (t) => `scale:${t};transform-origin:center center;` }}"
>
<Route path="/" component="{Home}" />
<Route path="/contact" component="{Contact}" />
</Router>
License
This project is licensed under the MIT.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for this project by you, shall be licensed as MIT, without any additional terms or conditions. Code of Conduct.