Svelte Dk Router
svelte-dk-router
An efficient, easy-to-use router for Svelte
Installation
npm i svelte-dk-router
or...
yarn add svelte-dk-router
Quick Start
First set your routes:
import { setRoutes } from 'svelte-dk-router'
import home from './views/home.svelte'
import about from './views/about.svelte'
import origins from './views/nested/origins.svelte'
import future from './views/nested/future.svelte'
import more from './views/nested/more.svelte'
import blog from './views/blog.svelte'
import fallback from './views/fallback.svelte'
const routes = [
{
name: 'Home',
// Update page title
title: 'Home',
path: '/',
component: home,
meta: {
name: 'dan'
}
},
{
// If no name passed,
// defaults to components' name
title: 'About',
path: '/about',
component: about,
children: [
{
name: 'Default About',
// Pass an empty path to display a default child
path: '',
component: future,
children: [
{
title: 'More | About',
// Full-path: /about/more
path: '/more',
component: more
}
]
},
{
title: 'Origins | About',
path: '/origins',
component: origins,
children: [
{
name: 'More About',
title: 'More | About',
// Full-path: /about/origins/more
path: '/more',
component: more
}
]
}
]
},
{
title: 'Blog',
// Named-params are specified with a colon
path: '/blog/:id/:name',
component: blog
},
// Define your fallback last
// Must have a path of '(*)'
{
name: 'Fallback',
title: '404',
path: '(*)',
component: fallback
}
]
setRoutes(routes)
// Or, for hash-based routing:
setRoutes(routes, true)
Then, use the view component:
<script>
import { SView } from 'svelte-dk-router';
</script>
<SView />
Links to navigate:
<script>
import { SLink } from 'svelte-dk-router';
let params = { id: '1', name: 'dan' };
let query = { id: '1', name: 'dan' };
let props = { some: 'extra information' };
</script>
<SLink name={'Home'}>Home</SLink>
// Using props allows you to pass any data to the next page
<SLink path={'/about'} {query} {props}>About</SLink>
<SLink path={'/blog'} {params} replace={true}>Blog</SLink>
// Navigate to a nested route
<SLink name={'More About'}>More Info</SLink>
// Full paths are also supported
<SLink path={'/about/origins/more'}>More Info</SLink>
Lastly, don't forget to set your Rollup config to handle SPA's with -s:
"scripts": {
...
"start": "sirv public -s",
}
API
NOTE: All navigations are asynchronous.
setRoutes(routes: array[object], hashMode?: boolean)
Set your routes and optionally set to hashMode (prepends all routes with /#).
If no name is set for a route, the components' name is used instead.
<SView />
The main view for your routes.
You can nest any number of views within your set components.
<SLink />
Link to each route. name or path are required, optional query, params (if defined), props and replace.
Dispatches a navigation event which returns an object with the success status and, if successful, the route being navigated to, else the error which was thrown.
replace defaults to false, meaning pushState is used instead of replaceState.
Example:
<SLink
name={string}
path={string}
query={object}
params={object}
props={any}
replace={boolean}
on:navigation={e => console.log(e.detail)} // e.detail = result
>
Slot for any link content
</SLink>
route
An object containing all information on the current route.
Example:
{
component: class Home,
// An array of route-names matching the current path
crumbs: ["Home"],
// Current route-depth
depth: 1,
fullPath: "/",
fullRegex: /^\/?$/i,
meta: { name: "dan" },
name: "Home",
path: "/",
query: { id: "1" },
regex: /^\/?$/i,
rootPath: "/",
title: "Home"
}
routeStore
A readable Svelte store which, through the .subscribe method, returns the current route whenever it's updated.
routeChart
An object containing a chart of all routes from the parent-route, down to the current route.
Example:
// Navigating to '/about' displays the default child route
1: {title: "About", path: "/about", children: Array(2), name: "About", component: ƒ, …}
2: {name: "Default About", path: "", children: Array(1), parent: {…}, component: ƒ, …}
routeChartStore
A readable Svelte store which, through the .subscribe method, returns the current route-chart whenever it's updated.
routeProps
A variable containing any data passed as props through <SLink />, push() or replace().
Resets to null on route change.
push(identifier: string, routeData?: object): current route
Programmatically changes the route using window.history.pushState().
identifier has to be the name or path of a route.
Returns a promise which can be chained:
await push('/')
.then(newRoute => /* Resolved */)
.catch(err => /* Rejected */);
Available properties you can pass:
await push('Blog', {
params: { id: '1', name: 'dan' },
query: { postTitle: 'how-to-use-svelte-dk-router' },
props: { post: blogPost }
})
replace(identifier: string, routeData?: object): current route
The same as push(), except, uses window.history.replaceState() instead.
beforeEach((to, from, setProps) => {})
Navigation guard to run before each route-change.
to contains all data for the route navigating to, from all data of the current route.
setProps allows you to set the value of routeProps (props in afterEach).
Note: Props can only be set once per navigation.
If async/await is used, the callback will be awaited before navigating.
If a redirect is initiated, the original navigation is cancelled and replaced with the redirect.
To cancel any navigation, return false.
Note: Set your navigation-guards before you call setRoutes, else, they won't run on page-load.
afterEach((to, from, props) => {})
Navigation guard to run after each route-change.
to contains all data for the route navigated to, from all data of the previous route.
props is essentially an alias for the routeProps import.
Note: Set your navigation-guards before you call setRoutes, else, they won't run on page-load.
setQuery(query: object, update?: boolean, replace?: boolean): current route
Programmatically set query params.
If update is set to true, replaces/adds to existing query.
Defaults to window.history.replaceState, if replace is set to false, uses window.history.pushState instead.
Returns a promise which resolves with the updated route data.
Example:
await setQuery({ new: 'query' })
.then(updatedRoute => /* Resolved */)
.catch(err => /* Rejected */);
setParams(params: object, replace?: boolean): current route
Programmatically update named-params. Params must be correctly defined for the current route.
Defaults to window.history.replaceState, if replace is set to false, uses window.history.pushState instead.
Returns a promise which resolves with the updated route data.
location properties
You can also import variables for each property of window.location:
import {
hash,
host,
hostname,
href,
origin,
pathname,
port,
protocol,
search
} from 'svelte-dk-router'
These variables update on each route change, ensuring simplicity and parity throughout your application.
.router-active
Any <SLink /> which matches the current-route/exists in the current-route heirarchy, has the class router-active applied.
In the spirit of a11y, the attribute aria-current="page" is also set using this method.
Contributions welcome.
