Need help with navaid?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

lukeed
656 Stars 24 Forks MIT License 90 Commits 5 Opened issues

Description

A navigation aid (aka, router) for the browser in 850 bytes~!

Services available

!
?

Need anything else?

Contributors list

# 5,104
CSS
vercel
argv
Crystal
86 commits
# 1,929
penetra...
phantom...
svd
python-...
1 commit
# 17,464
Ruby
Markdow...
Sublime...
vuejs
1 commit
# 46,674
Sass
TypeScr...
dropzon...
Svelte
1 commit
# 547
JavaScr...
play-fr...
playfra...
datadog
1 commit
navaid
A navigation aid (aka, router) for the browser in 865 bytes~!

Install

$ npm install --save navaid

Usage

const navaid = require('navaid');

// Setup router let router = navaid(); // or: new Navaid();

// Attach routes router .on('/', () => { console.log('> /'); }) .on('/users/:username', params => { console.log('> /users/:username', params); }) .on('/books/', params => { console.log('~> /books/', params); });

// Run as single instance router.run('/'); //=> "> /" router.run('/users/lukeed'); //=> "> /users/:username { username: 'lukeed' }" router.run('/books/kids/narnia'); //=> "~> /books/* { wild: 'kids/narnia' }"

// Run as long-lived router w/ history & "" bindings // Also immediately calls run() handler for current location router.listen();

API

navaid(base, on404)

Returns:

Navaid

base

Type:

String

Default:
'/'

The base pathname for your application. By default, Navaid assumes it's operating on the root.

All routes will be processed relative to this path (see

on()
). Similarly, while
listen
ing, Navaid will not intercept any links that don't lead with this

base
pathname.

Note: Navaid will accept a

base
with or without a leading and/or trailing slash, as all cases are handled identically.

on404

Type:

Function

Default:
undefined

The function to run if the incoming pathname did not match any of your defined defined patterns.
When defined, this function will receive the formatted

uri
as its only parameter; see
format()
.

Important: Navaid only processes routes that match your

base
path!
Put differently,
on404
will never run for URLs that do not begin with
base
.
This allows you to mount multiple Navaid instances on the same page, each with different
base
paths. :wink:

format(uri)

Returns:

String
or
false

Formats and returns a pathname relative to the

base
path.

If the

uri
does not begin with the
base
, then
false
will be returned instead.
Otherwise, the return value will always lead with a slash (
/
).

Note: This is called automatically within the

listen()
and
run()
methods.

uri

Type:

String

The path to format.

Note: Much like

base
, paths with or without leading and trailing slashes are handled identically.

route(uri, replace)

Returns:

undefined

Programmatically route to a path whilst modifying & using the

history
events.

uri

Type:

String

The desired path to navigate.

Important: Navaid will prefix your

uri
with the
base
, if/when defined.

replace

Type:

Boolean

Default:
false

If

true
, then
history.replaceState
will be used. Otherwise
history.pushState
will be used.

This is generally used for redirects; for example, redirecting a user away from a login page if they're already logged in.

on(pattern, handler)

Returns:

Navaid

Define a function

handler
to run when a route matches the given
pattern
string.

pattern

Type:

String

The supported pattern types are:

  • static (
    /users
    )
  • named parameters (
    /users/:id
    )
  • nested parameters (
    /users/:id/books/:title
    )
  • optional parameters (
    /users/:id?/books/:title?
    )
  • any match / wildcards (
    /users/*
    )

Note: It does not matter if your pattern begins with a

/
— it will be added if missing.

handler

Type:

Function

The function to run when its

pattern
is matched.

Note: This can also be a

Promise
or
async
function, but it's up to you to handle its result/error.

For

pattern
s with named parameters and/or wildcards, the
handler
will receive an "params" object containing the parsed values.

When wildcards are used, the "params" object will fill a

wild
key with the URL segment(s) that match from that point & onward.
let r = new Navaid();

r.on('/users/:id', console.log).run('/users/lukeed'); //=> { id: 'lukeed' }

r.on('/users/:id/books/:title?', console.log).run('/users/lukeed/books/narnia'); //=> { id: 'lukeed', title: 'narnia' }

r.on('/users/:id/jobs/*').run('/users/lukeed/jobs/foo/bar/baz/bat'); //=> { id: 'lukeed', wild: 'foo/bar/baz/bat' }

run(uri)

Returns:

Navaid

Executes the matching handler for the specified path.

Unlike

route()
, this does not pass through the
history
state nor emit any events.

Note: You'll generally want to use

listen()
instead, but
run()
may be useful in Node.js/SSR contexts.

uri

Type:

String

Default:
location.pathname

The pathname to process. Its matching

handler
(as defined by
on()
) will be executed.

listen(uri?)

Returns:

Navaid

Attaches global listeners to synchronize your router with URL changes, which allows Navaid to respond consistently to your browser's BACK and FORWARD buttons.

These are the (global) events that Navaid creates and/or responds to:

  • popstate
  • replacestate
  • pushstate

Navaid will also bind to any

click
event(s) on anchor tags (
) so long as the link has a valid
href
that matches the
base
path. Navaid will not intercept links that have any
target
attribute or if the link was clicked with a special modifier (eg; ALT, SHIFT, CMD, or CTRL).

uri

Type:

String

Default:
undefined

(Optional) Any value passed to

listen()
will be forwarded to the underlying
run()
call.
When not defined,
run()
will read the current
location.pathname
value.

unlisten()

Returns:

undefined

Detach all listeners initialized by

listen()
.

Note: This method is only available after

listen()
has been invoked.

License

MIT © Luke Edwards

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.