matthewrobb/yrv

Your routing bro!

The v is for Svelte

Built on top of abstract-nested-router, so you can use nested routers, also:

• Advanced parameters can be used, e.g. /:id<\d+> — see docs
• ARIA-compliant, sets [aria-current="page"] on active links
• Seamless <base href="..." /> integration
• Conditionals and redirection through props
• Fallback <Route /> handlers
• Hash and URI-based routes
• Support for query-string
• REPL ready!

yrv will use any base-href found on the current page to rewrite links and routes.

Usage

Install yrv through NPM or Yarn:

<script>
  import { Router, Route, Link } from 'yrv';
</script>

<Link href="/">Home</Link>
| <Link href="/World">Hello</Link>
| <Link href="/not/found">NotFound</Link>

<p>
  <Router>
    <Route exact>Hello World</Route>
    <Route fallback>Not found</Route>
    <Route exact path="/:name" let:router>Hey {router.params.name}!</Route>
  </Router>
</p>

Notice fallback routes can’t be placed at the beginning, otherwise further routes will not be mounted. 💣

Components

You MUST declare at least, one top-level Router to setup the bindings.

<Router {path} {disabled} {condition} {nofallback} />

This component will hold any given routes as children, path is always derived from parent ones.

Available props:

• {path} — Any segment to derive a fullpath from, default to /
• {disabled} — Boolean; Similar to condition, but for bound props
• {condition} — Function; if given, render only if evaluates to true
• {nofallback} — If set, non-matched routes will never raise a failure

<Route {key} {path} {props} {exact} {fallback} {component} {disabled} {condition} {redirect} let:router />

Main container for routing, they can hold any component or children.

Available props:

• {key} — The route identity, not its path; default to random pseudo-hash
• {path} — Any segment to derive a fullpath from, default to /
• {props} — Additional properties for rendered component
• {exact} — If set, the route will render only if the route exactly matches
• {fallback} — If set, the route will render only if no more routes were matched
• {component} — A valid svelte-component to render if the route matches
• {disabled} — Boolean; Similar to condition, but for bound props
• {condition} — Function; if given, the route will render only if evaluates to true
• {redirect} — Alternate redirection location, only if the previous condition was true
• let:router — Injects the router context, it also provides failure in case of errors

If you omit exact, then /x would match both / and /x routes — see docs

<Link {go} {href} {title} {exact} {reload} {replace} {class|className} />

In order to navigate, you can use Link components, or regular links, etc.

All href values MUST be absolute, only links starting with / or # are allowed.

Available props:

• {go} — History shortcut (see below)
• {href} — New location, default to /
• {title} — HTML title-attribute value
• {button} — If set, will use button-tag instead
• {exact} — Determine if link should match exactly to be set as active
• {reload} — Use location.href instead
• {replace} — Use history.replaceState() instead
• {class|className} — Custom class-name for the mounted anchor

Normal on:click events are still allowed, so you can use:

<Link on:click={() => location.reload()}>Reload</Link>

Active links will gain the [aria-current] attribute, and [disabled] if they're buttons.

Aditionally, you can setup go to moving around:

• "back" — String; if given, will invoke history.back()
• "fwd" — String; if given, will invoke history.fwd()
• n — Number; if given, it'll be used to invoke history.go(n)

If navigating through history is not possible a normal redirection will run. ⚓

Public API

• navigateTo(path[, options]) — Change the location, supported options are:
  • reload — If true, it will use document.location.href instead
  • replace — If true, it will use history.replaceState() instead
  • params — Used to replace :placeholders from given path
  • queryParams — Additional search-params for the new location
• $router — Store with shared routeInfo details, similar to let:router

yrv gracefully degrades to location.hash on environments where history is not suitable, also it can be forced through Router.hashchange = true.