svelte-micro
TypeScript icon, indicating that this package has built-in type declarations

2.5.6 • Public • Published

Svelte Micro

Light & reactive client-side router for Svelte

Announcement of svelte-micro v3

Table of content

Installation

npm i svelte-micro

Example

<script>
  import { Route, Link, linkHandle } from "svelte-micro"
</script>

<!-- Root component path always have to be equal to '/' -->
<Route>
  <!-- Always will be shown -->
  <nav use:linkHandle>
    <a href="/">Home</a>
    <a href="/portfolio">Portfolio</a>
    <a href="/about-us/story">Our story</a>
    <a href="https://github.com/ayndqy/svelte-micro">Github</a>
  </nav>

  <!-- Will be shown only when $path is equal to '/' -->
  <Route path="/">
    <h1>Home page</h1>
    <p>Make yourself at home.</p>
  </Route>

  <Route path="/portfolio">
    <h1>Portfolio</h1>

    <!-- Will be shown only when $path is equal to '/portfolio' -->
    <Route path="/">
      <h2>Portfolio main page</h2>
      <Link href="/portfolio/sites">Sites</Link>
      <Link href="/portfolio/apps">Apps</Link>
    </Route>

    <Route path="/sites">
      <h2>Sites</h2>
      <Link href="/portfolio">Back to portfolio main page</Link>
    </Route>

    <Route path="/apps">
      <h2>Apps</h2>
      <Link href="/portfolio">Back to portfolio main page</Link>
    </Route>

    <Route fallback>
      <h2>The route is not found in /portfolio</h2>
      <Link href="/portfolio">Back to portfolio main page</Link>
    </Route>
  </Route>

  <Route path="/about-us/story">
    <h1>Our story</h1>
  </Route>

  <Route fallback>
    <h1>The route is not found</h1>
    <Link href="/">Back to home</Link>
  </Route>
</Route>

This code shows the capabilities of the svelte-micro routing system.
Spend a minute analyzing this example to understand the approach.

For advanced examples see the Tips section.

API

Imports reference

Entity Related imports
router object import { router, type Router } from 'svelte-micro'
options store import { options, type OptionsStore, type Options } from 'svelte-micro'
path store import { path, type PathStore, type Path } from 'svelte-micro'
query store import { query, type QueryStore, type Query } from 'svelte-micro'
hash store import { hash, type HashStore, type Hash } from 'svelte-micro'
Route component import { Route } from 'svelte-micro'
Link component import { Link } from 'svelte-micro'
linkHandle action import { linkHandle, type LinkHandle } from 'svelte-micro'
getPathSegments function import { getPathSegments, type GetPathSegments } from 'svelte-micro'

router object

Type definition

type Router = {
  go: (delta?: number) => void
  push: (url?: string | URL | null, state?: any) => void
  replace: (url?: string | URL | null, state?: any) => void
}

Description

The router object is an object whose methods allow to manipulate history.

  • router.go
    Move on delta steps through the history.

  • router.push
    Push new url and state to the history.

  • router.replace
    Replace current url and state in the history.

options store

Type definition

type OptionsStore = {
  subscribe: import('svelte/store').Readable<Options>['subscribe']
  set: (changedOptions: Partial<Options>) => void
}
type Options = {
  mode: 'window' | 'hash'
  basePath: null | string
}

Description

The options store provides subscribe and set methods to access and modify router options.

  • $options.mode
    Default: 'window'
    Set the mode for the router.

  • $options.basePath
    Default: null
    Set the basePath for the router.
    If a basePath value is not found at the beginning of $path, the router will continue to operate properly, ignoring the basePath option for this state of $path. Be aware that if mode is set to 'hash', the router will try to find the basePath value in the hash location fragment, since the hash location fragment is already separated from the path location fragment.

path store

Type definition

type Path = string
type PathStore = import('svelte/store').Readable<Path>

Description

The store which contains current path.

query store

Type definition

type Query = string
type QueryStore = import('svelte/store').Readable<Query>

Description

The store which contains current query.

hash store

Type definition

type Hash = string
type HashStore = import('svelte/store').Readable<Hash>

Description

The store which contains current hash.

Route component

Type definition

<!--
  props: { fallback: boolean; path: string; };
  slots: { default: {}; };
-->
<Route fallback={false} path="/"> <slot /> </Route>

Description

The Route component defines a route. The props of Route are reactive. A nested Route component works in context of its parental Route component, so you don't need to define its full path.

  • fallback
    Default: {false} The property which defines if the route is fallback. A fallback route is active when there is no active routes on its depth.

  • path
    Default: '/' The property which defines route path. path must start from '/'.

The top-level (root) Route must have path equal to '/' and fallback equal to false.
These values are set by default, so you can leave them unchanged (see Example section).

Link component

Type definition

<!--
  props: { href: string; [x: string]: any; };
  slots: { default: {}; };
-->
<Link href="/" {...restProps}> <slot /> </Link>

Description

The <Link /> component is built on top of linkHandle and should be used for the internal application navigation.
It automatically prevents the window from refreshing.

  • href
    Default: '/' The property which defines link href.

  • {...restProps}
    Any other property is attached on the inner a element.

If the basePath option isn't set to null, the <Link /> component will append the basePath value to the href attribute.
If the mode option is set to "hash", the <Link /> component will append a # to the beginning of the href attribute.

linkHandle action

Type definition

type LinkHandle = import('svelte/action').Action<HTMLElement>

Description

The linkHandle action prevents window from refreshing when the click event occurs on a handled a[href] element.
linkHandle can be applied on a parental element to handle nested a[href] elements.

linkHandle ignores an a[href] element if:

  • a[href] has data-handle-ignore attribute
  • a[href] has target attribute which isn't equal to '_self'
  • a[href] has external href (new URL(href).origin !== document.location.origin)
  • (event.ctrlKey || event.metaKey || event.altKey || event.shiftKey) === true during the click event

getPathSegments function

Type definition

export type GetPathSegments = (path: string) => string[]

Description

The getPathSegments function divides path into segments.

For example: getPathSegments('/about-us/story') => ['/about-us', '/story'].

Tips

path, query, hash usage

<script>
  import { path, query, hash } from 'svelte-micro'

  // For example current location equals to '/somepath?text=Hello#modal'
  // $path  === '/somepath'
  // $query === '?text=Hello'
  // $hash  === '#modal'

  $: text = new URLSearchParams($query)?.get('text') ?? 'Fallback value'
</script>

<!-- Query usage example -->
{text}

<!-- Hash usage example -->
{#if $hash === '#modal'}
  <div class="modal">Hello from modal!</div>
{/if}

Scroll behavior control

import { path } from 'svelte-micro'

// Disable browser scroll behavior control
if ('scrollRestoration' in history) {
  history.scrollRestoration = 'manual'
}

// On path change reset scroll position
path.subscribe(() => window.scrollTo(0, 0))

By default svelte-micro doesn't control scroll behavior, but it's easy to do on your own.

Redirect

<script>
  import { router, Route } from 'svelte-micro'
</script>

<Route>
  <Route path="/redirect">
    {router.replace('/redirect-target')}
  </Route>

  <Route path="/redirect-target">
    <h1>You have been redirected</h1>
  </Route>
</Route>

Guarded route

<script>
  import { Route } from 'svelte-micro'

  let isUserAuthenticated = false
  const toggleAuth = () => (isUserAuthenticated = !isUserAuthenticated)
</script>

<Route>
  <Route path="/auth">
    <button on:click={toggleAuth}>{isUserAuthenticated ? "Log out" : "Log in"}</button>
  </Route>

  {#if isUserAuthenticated}
    <Route path="/profile">
      <h1>Welcome!</h1>
      <button on:click={toggleAuth}>Log out</button>
    </Route>
  {/if}
</Route>

Readme

Keywords

Package Sidebar

Install

npm i svelte-micro

Weekly Downloads

64

Version

2.5.6

License

MIT

Unpacked Size

27.3 kB

Total Files

24

Last publish

Collaborators

  • ayndqy