intermundos / 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} {dynamic} {pending} {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
• {dynamic} — Promise, if set will resolve and use its result as lazy-component
• {pending} — String, this value is rendered during the loading of dynamic components
• {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} {open} {title} {exact} {reload} {replace} {class} />

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 /
• {open} — Same behavior as <a target="_blank">
• {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} — Custom class-name for the mounted anchor

The value for open can be a string including the window specs, e.g. width=400,height=200 — a on:close event will be fired once the opened window is closed.

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.

IE11 support

Support for IE11 is granted if you include, at least, the following polyfills before your application:

<script>if (!!window.MSInputMethodContext && !!document.documentMode)
  document.write('<script src="https://polyfill.io/v3/polyfill.min.js?features=default,Promise,Object.getOwnPropertyDescriptors"><\/script>');</script>
<script src="your-app.js"></script>

document.write() is used because conditional comments were dropped in IE10, so this way you can conditionally load polyfills anyway.

Also, you MUST to enable either buble or babel within your build pipeline to transpile down to ES5.