Swheel

Declarative component-based svelte 3 router.

Examples

Install

npm i --save swheel

API

• <Router />
• <MemoryRouter />
• getHistory()
  • history methods
  • history stores
• navLink
• <Route />
• <Layout />
• <HashRoute />
• <Fallback />
• <Redirect />
• <BeforeLeave />
• <Protected />

<Router />

Should be placed on the top of your application. Applies special listener for every <a> element and initializes routing state for application's tree.

Uses browser history API.

<MemoryRouter />

The same as <Router> but uses in-memory history API.

getHistory: Function

Function that returns object of helper functions to work with history.

This function should be called in the component's initialization step bacause Router and MemoryRouter uses svelte's context API as a core approach

Methods:

Name	Arguments	Description
push	path: String	Push path to the history
replace	path: String	Replace path in the current state of the history
back	-	Move back in the history
forward	-	Move forward in the history

Stores:

Name	Subject	Description
currentPath	currentPath: String	Current path in history
stack (<MemoryRouter> only)	{ stack, hasNext, hasPrev }	Set of fields with memory histories' metadata

navLink: Function

Svelte action. Allows to control active class (show/hide it) in case of matching href attribute with current path of history. Active class name should be defined explicitly to be compiled with svelte.

Ex. <a use:navLink={{ exact: true, activeClass: 'active' }} class="active" href="/path" />

Parameters:

Name	Type	Default / required	Description
exact	Boolean	false	If pathes should have exactly matches
activeClass	String	'active'	Class name that will be assigned in case of pathes matches

<Route />

Specifies your route configuration.

It is possible to define nested to routes.
In this case all pathes will calculate relatively the parent path.
Ex. If parent route defined as <Route path="/parent" /> and child as <Route path="/child" /> - in this case nested route will be resolved by path /parent/child.

Prop	Type	Default / required	Description
path	String	required	Path to access the route. Could be defined as template with required and optional parameters (ex. /pokemon/:id). If path matched than parameters passing inside components from lazy or component as property (ex. export let id) or could be accessed from let:params and passed to the slot.
let:params	Object	null	Parameters resolved from path
exact	Boolean	false	Detects if path should have exactly matches
when	Boolean	true	Detects if route is using in current flow
component	SvelteComponent	null	Renders in case if path matched
lazy	() => Promise<SvelteComponent>	null	Function that returns promise that resolving the Svelte component Loading starts only on the first route matching and after that component will cache
throttle	Number	0	Uses in a couple with lazy. Determines minimal time (in ms) which component will not be displayed. Necessary for preventing flash effect when switching pending state to component.
<slot />	SvelteSlot	-	Renders in the case if lazy or component props was't defined
<slot name="pending" />	SvelteSlot	-	Renders when component from lazy field is loading
<slot name="catch" />	SvelteSlot	-	Renders when component from lazy field is failed to load

<Layout />

Provides the possibility to declaratively define layouts around the group of routes and will be rendered only in the case if any path of these routes matches.

Prop	Type	Default / required	Description
component	SvelteComponent	required	Layout component that wraps the group of routes. <slot/> content of <Layout> will be passed to it. Renders only in case if any path of inner routes matches.
when	Boolean	true	Detects if layout and it routes' group is using in current flow
<slot />	SvelteSlot	-	Will be passed to the component.

<HashRoute />

Extends <Route> without path property and expands with own ones.

Route that displays content, when history hash (#) matches.

Prop	Type	Default / required	Description
hash	String	required	Should start with #
let:removeHash	Function	-	Passes to component or lazy as property. Function that allows to remove hash from history. Usefull in a couple with modals etc.

<Fallback />

Extends <Route> without path property.

Renders component from lazy, component or <slot /> if any defined route wasn't rendered.
Usefull for 404 (NotFound) pages.

<Redirect />

Determines overriding of current location.
Nested redirect will define from path relatively to the parent route's path.

Prop	Type	Default / required	Description
to	String	required	Defines path to which redirect in case of from matched
from	String	'*'	Determines the path that should be overrided. If * specified than redirect will be triggered from path that doesn't matched for any route.
exact	Boolean	false	Detects if path of from property should have exactly matches

<BeforeLeave />

Provides possibility to prevent leaving from the page.

Usefull if there is a form on the page and in the case of it's filled to prevent leaving.

Prop	Type	Default / required	Description
shouldDetectLeave	Boolean	true	Detects if leaving should be detected
let:isLeaving	Boolean	true	Detects if user trying to leave the page
let:cancelLeave	Function	-	Cancel transition from the page
let:acceptLeave	Function	-	Accept transition from the page. User will be moved to the page where he tried to go before.
<slot />	SvelteSlot	-	Child content of the component

<Protected />

Protects displaying of nested routes. If routes was wrapped with some content before - it (content) will be displayed in any case. Uses as an abstraction for <Layout /> but could be usefull in some special cases.

Prop	Type	Default / required	Description
when	Boolean	true	Detects if routes should be displayed in the subtree

TODO

1. Recipe for SSR
2. Unit tests
3. Typings