Router

Constructor

constructor({
  routes,
  base = '',
  pathQuery = '',
  clientContext,
  callLoadOnClient = false
}: {
  routes: ViewConfigGroup
  base?: string
  pathQuery?: string
  clientContext?: unknown
  callLoadOnClient?: boolean
})

routes

The route configuration. Refer to routing for usage.

base

The base path of the application.

If your application is deployed in a subdirectory of a domain, like https://www.example.com/app/, in this case, the base path would be /app/. If you prefer the root path not to end with a slash, you can set the base without a trailing slash, like /app.

When you navigate to a URL, if you pass an absolute URL starting with the protocol (for example, https://www.example.com/app/my-route), the base path will be trimmed during matching. But if the path you pass does not include the protocol, like /app/my-route, the base path will not be trimmed. Example:

const router = new Router({
  base: '/app',

  routes: [
    {
      component: () => import('./User.svelte'),
      path: '/user'
    }
  ]
})

// Correct
router.push('http://127.0.0.1/app/user')

// Correct
router.push('/user')

// Incorrect
router.push('/app/user')

pathQuery

Uses query parameters as the routing path. This feature can be useful when providing applications under the file: protocol, for example:

const router = new Router({
  pathQuery: '__path__',
  // ...
})

In the example above, if we visit file:///path/to/index.html?__path__=/home, the /home route will be matched.

clientContext

The context object when calling the load function on the client side. Creating this object might require client-specific APIs, so it is generally set in the Router.start() method. Refer to server-side rendering for usage.

callLoadOnClient

Indicates whether to call the load function on the client side.

current

The current Route object. Available only on the client side.

start()

start(
  onReady: () => void,
  {
    clientContext,
    ssrState,
    path
  }: {
    clientContext?: unknown
    ssrState?: SSRState
    path?: string | Location
  } = {}
): void

Starts the router. Available only in client mode.

onReady

A callback function called when the router is ready. We need to create a ClientApp instance in this callback. Refer to creating a new project for usage.

clientContext

Sets the clientContext attribute of the Router instance.

ssrState

Provides the data returned by the server’s load function to the client for hydration.

path

Used to initialize the router's path. It can be a URL string or a Location type object. It defaults to the current webpage's URL. If the provided URL is different from the current webpage’s URL, it will call Router.handleClient() to render the corresponding route but not navigate. This parameter can be used to prevent page navigation, for instance, when the server renders a 404 or 500 page.

handleClient()

handleClient(location: string | Location, ssrState?: SSRState): Promise<Route | undefined | false>

A router method used for handling navigation during client-side rendering. Use this method if you want to render a route but don’t want history.pushState() or history.replaceState() to be executed. If a Route type object is returned, it means the route was matched and successfully rendered. If undefined is returned, no route was matched. If false is returned, a route was matched but was intercepted by a route guard.

handleServer()

handleServer(location: string | Location, loadFunctionContext?: unknown): Promise<Route | undefined>

A router method used for handling requests during server-side rendering. Refer to server-side rendering for details.

parseLocation()

parseLocation(location: string | Location): Pick<Route, "path" | "query" | "search" | "hash" | "state" | "href">

Parses a Location type object or URL string and returns a subset of the Route object:

{
  path,
  query,
  search,
  hash,
  state,
  href
}

href()

href(location: string | Location): string

A URL string that can be assigned to the href attribute of an <a> tag and the location.href attribute. If your router is based on pathQuery, it will include search and hash but not path, because routers based on pathQuery do not care about the path.

push()

push(location: string | Location): Promise<void>

Navigates to location and calls history.pushState() to change the current page's URL.

replace()

replace(location: string | Location): Promise<void>

Navigates to location and calls history.replaceState() to change the current page's URL.

setState()

setState(state: Record<string, unknown>): void

Merges state into the current route’s state and calls history.replaceState().

go()

go(position: number, state?: Record<string, unknown>): void

Calls history.go(). If state is set, it will merge state into the destination route’s state and call history.replaceState().

back()

back(state?: Record<string, unknown>): void

An alias for router.go(-1, state).

forward()

forward(state?: Record<string, unknown>): void

An alias for router.go(1, state).

on()

router.on('beforeChange', handler: NavigationGuard)
router.on('beforeCurrentRouteLeave', handler: NavigationGuard)
router.on('update', handler: UpdateHandler)
router.on('afterChange', handler: AfterChangeHandler)
router.on('error', handler: ErrorHandler)

type NavigationGuardResult = void | boolean | string | Location

type NavigationGuard = (
  to: Route,
  from?: Route
) => NavigationGuardResult | Promise<NavigationGuardResult>

type AfterChangeHandler = (to: Route, from?: Route) => void
type UpdateHandler = (route: Route) => void
type ErrorHandler = (error: unknown) => void

Listens to router events.

beforeChange

Triggered before the route changes. For detailed usage, refer to Route Guards.

beforeCurrentRouteLeave

Triggered before leaving the current route. The event handler is only registered in the current route and will be removed once the route changes.

update

Triggered when the new route is successfully loaded.

afterChange

Triggered after the route changes.

error

Triggered when an error occurs during the route change.

Event Trigger Sequence

Call the beforeLeave event handlers in the view tree of the route that is about to be left.
Call the beforeCurrentRouteLeave event handler.
Call the beforeChange event handler.
Call the beforeEnter event handlers in the view tree of the incoming route.
Call the beforeEnter event handler exported in the <script module> of synchronously loaded Svelte components.
Call the beforeEnter event handler exported in the <script module> of asynchronously loaded Svelte components.
Call the update event handler.
Call the afterChange event handler.

off()

router.off(event: Event, handler: EventHandler)

Removes the event listener from the router.

once()

router.once(event: Event, handler: EventHandler)

Listens to a router event, but will be triggered only once.

Route

interface Route {
  hash: string
  href: string
  meta: Record<string, unknown>
  params: StringCaster
  path: string
  query: StringCaster
  search: string
  ssrState: SSRState
  state: Record<string, unknown>
}

The Route type object describes the information of the matched route. It consists of the following properties:

path

A string starting with /, excluding the query string or fragment identifier.

query

A StringCaster object containing the query parameters.

search

A string starting with ?, representing the URL query string.

hash

A string starting with #, followed by the URL fragment identifier.

state

A history.state object.

params

A StringCaster object containing the path parameters.

href

A URL string that can be assigned to the href attribute of an <a> tag and the location.href attribute. If your router is based on pathQuery, it will include search and hash but not path, as routers based on pathQuery are not concerned with the path.

ssrState

A JSON serializable object used for passing data during server-side rendering and client-side hydration.

Location

interface Location {
  hash?: string
  params?: Record<string, boolean | number | string>
  path: string
  query?: Record<string, PrimitiveType | PrimitiveType[]> | URLSearchParams
  state?: Record<string, unknown>
}

The Location type object is used to describe the destination of navigation. It can consist of the following properties:

path

A string starting with /. It can include a query string and fragment identifier, but it's not recommended, as you'll need to handle encoding manually.

params

Path parameters. A key-value pair object used to fill the parameter placeholders in path. For example, { path: '/articles/:id', params: { id: 123 } } is equivalent to { path: '/articles/123' }. Using params is safer than manually concatenating strings, as the parameter values are automatically encoded with encodeURIComponent().

query

Query parameters. If a plain object is provided, its format is similar to the return value of the parse() method of the querystring module:

{
  foo: 'bar',
  abc: ['xyz', '123']
}

hash

A string starting with #, followed by the URL fragment identifier.

state

Used to set history.state.

Miscellaneous

Accessing `Router` Instance and `$route` Store from Component Context

Although rarely needed, you can access the Router instance and $route store from the component context:

<script>
  import { getContext } from 'svelte'

  const router = getContext('__SVELTE_PILOT_ROUTER__')
  router.push('/foo')

  const routeStore = getContext('__SVELTE_PILOT_ROUTE__')
  console.log($routeStore.path)
</script>

For instance, the <Link> component accesses the Router instance in this way.

Router

Constructor

routes

base

pathQuery

clientContext

callLoadOnClient

current

start()

onReady

clientContext

ssrState

path

handleClient()

handleServer()

parseLocation()

href()

push()

replace()

setState()

go()

back()

forward()

on()

beforeChange

beforeCurrentRouteLeave

update

afterChange

error

Event Trigger Sequence

off()

once()

Route

path

query

search

hash

state

params

meta

href

ssrState

Location

path

params

query

hash

state

Miscellaneous

Accessing Router Instance and $route Store from Component Context

Accessing `Router` Instance and `$route` Store from Component Context