@bjornlu/svelte-router

Svelte Router

An easy-to-use SPA router for Svelte.

npm install @bjornlu/svelte-router

Comparison with other routers

Features

• Super simple API
• Support hash and path based navigation
• Auto base tag navigation
• Easy redirection and navigation guards (with async support)
• Define all routes in one object
• Nested routes

Not supported

• Server-side rendering (SSR) - Use Sapper or Routify instead
• Relative navigations - Use absolute path and param shorthand syntax instead

Table of contents

• Usage
• API
  • <Link />
  • navigate
  • route
• Recipes

Usage

// router.js

import { initRouter } from '@bjornlu/svelte-router'
import Home from './Home.svelte'
import Profile from './Profile.svelte'
import ProfileWelcome from './ProfileWelcome.svelte'
import ProfileBio from './ProfileBio.svelte'
import Null from './Null.svelte'

// Initialize the router
initRouter({
  // The routing mode: "hash" or "path"
  mode: 'history',
  // Define routes from the most specific to the least specific
  routes: [
    {
      path: '/',
      component: Home
    },
    {
      // Use ":variable" to use named parameters
      path: '/profile/:id',
      // Component with childrens must have a <slot />
      component: Profile,
      children: [
        {
          path: '/welcome',
          component: ProfileWelcome
        },
        {
          path: '/bio',
          component: ProfileBio
        }
      ]
    },
    {
      path: '/secret',
      // Redirect to a new path if this route is matched.
      // Also accepts a function that returns a string, and may be asynchronous.
      // Learn more in the Recipes section.
      redirect: '/'
    },
    {
      path: '/*',
      component: Null
    }
  ]
})

<!-- App.svelte -->

<script>
  import { RouterView } from '@bjornlu/svelte-router'
</script>

<main>
  <RouterView />
</main>

// main.js

import App from './App.svelte'
import './router'

const app = new App({
  target: document.getElementById('app')
})

export default app

API

<Link />

Prop	Type	Default	Description
to	string | LocationInput		Target route
replace	boolean	false	Replace current route instead of pushing

• Renders an anchor tag
• Adds aria-current="page" when link exactly matches
• Display correct href by resolving base path, param shorthand paths and hash prepends, e.g. /foo/:id => /foo/123
• Adds active class names based on to and current route path:
  • link-active when link partially matches, e.g. /foo matches /foo/bar
  • link-exact-active when link exactly matches, e.g. /foo matches /foo

navigate

navigate has two function signatures:

1. navigate(to: number)

Navigate using an offset in the current history. Works the same way as history.go.

1. navigate(to: string | LocationInput, replace?: boolean)

Navigate to a route using a string or an object. string and LocationInput are semantically equal and are just different ways to express the same route. For example:

'/foo?key=value#top'

// same as

{
  path: '/foo',
  search: { key: 'value' },
  hash: '#top'
}

Both string's path and LocationInput's path can take advantage of the param shorthand syntax to easily define absolute route navigation.

Example usage:

navigate('/foo/bar')
navigate('/foo/bar?key=value')
navigate('?key=value')
navigate('#hey', true)
navigate('#/foo/bar')
navigate({ path: '/foo/bar', search: { key: 'value' } })
navigate({ path: '/foo/:id', hash: '#hey' })
navigate({ search: '?key=value' })

In hash mode, path will take precedence over hash. e.g. /foo#/bar will navigate to /foo.

route

Svelte Router exports a readable store route that contains the current route information.

Property	Type	Example	Description
path	string	'/foo'
params	Record	{ id: '123' }	The parsed path parameters, e.g. /foo/:id
search	URLSearchParams		The path search parsed with URLSearchParams
hash	string	'#hey'	The path hash with leading #. Empty string if no hash.
matched	RouteRecord[]		The array of route records for all nested path segments of the current route. The matched records reference the records defined in the routes configuration.

Advanced usage

Check out the recipes section for more advanced use-cases and solutions.

Contributing

All contributions are welcomed. For any major changes, please open an issue first :)

License

MIT

Changelog

0.2.1 - 2020-09-01

Fixed

• <Link /> will work properly with special key clicks, e.g. ctrl-click