svelte-querystring-router

A client-side router that only serializes a small amount of state to the querystring.

Use case

Svelte is a new kind of component library, in that its footprint is so small that you can justifiably use it on a standalone HTML page that has a small amount of dynamic content.

Normally you would want to avoid pulling in a component framework to put a component or two on a single page, but since Svelte doesn't have the overhead of runtime code to ship to the browser, you can toss a few components onto a small page without any guilt.

These single pages don't need a full router, but you should still serialize any dynamic state to the url. That's where this library comes in.

Note: don't use this library if you want a client-side router to display different Svelte components as pages based on the route. If you have a true single-page application with multiple pages, you should use abstract-state-router. Check out Why your webapp needs a state-based router for more details.

What it does

1. Gives you a <Link> component your components can use to generate links that update the querystring without reloading the page
2. Keeps a querystringParameters parameter up to date on your top-level components when the querystring changes

Usage

To use the Link component in your components:

<p>
    You can totally click <Link parameters="{ { thingy: 'yes' } }">this</Link>
</p>
{#if querystringParameters.thingy === 'yes'}
<p>
    Aw, yeah.
</p>
{/if}
 
<script>
const { Link } = require('svelte-querystring-router')
 
export default {
    components: {
        Link
    }
}
</script> 

To hook up the query string to your component, so that the querystringParameters value is populated, do this wherever you're instantiating your component:

const { attachQuerystringData, getCurrentParameters } = require('svelte-querystring-router')
 
const component = new YourCoolComponent({
    target: document.getElementById('whatever'),
    data: {
        querystringParameters: getCurrentParameters()
    }
})
 
attachQuerystringData(component) // This keeps querystringParameters updated

How it works

Clicks on <Link> elements are intercepted and turned into pushState calls, so that the page doesn't reload on every click.

Whenever this happens, all the components that you hooked up with attachQuerystringData() have their querystringParameters data changed - any display values based on that data will change instantly without any page reloading.

API

When you import the module, you get a global instance based on the browser's location/history globals.

It is possible to create an instance passing in shims for these functions, but I don't know if there's any use for that yet.

Anyway, the instantiated instances come with this API:

attachQuerystringData(component)

Link

The component to be used in other Svelte components. Creates an <a href> based on the parameters you pass in.

Takes these attributes:

• className: a string of class names to be applied to the a element
• style: a style string to be applied to the a element
• parameters: an object of properties to be turned into a querystring link

navigate({ parameters, [querystring], [element], [replace] })

Causes a pushState, and fires a navigate event, updating all attached components.

If replace is truthy, then replaceState is called instead of pushState.

currentQuerystring = getCurrentQuerystring()

currentParameters = getCurrentParameters()

Events

There are two event-listening methods:

• removeListener = on(event, listener)
• removeListener = once(event, listener)

These events are fired:

• before navigate
• navigate - this is when pushState is called
• after navigate

All events emit a single object as an argument, with three properties: querystring, parameters, and element.

License

WTFPL