unurl

Simple reactive URL object

Note: uses Proxy, check browser support before using.

Install

npm i unurl

Usage

const { url, onChange } = require('unurl')

onChange(() => {
  // Fires when url changes
})

function changeURL() {
  url.pathname = '/new-path'
  url.searchParams.append('foo', 'bar')
}

const { url } = require('unurl')
const { connect } = require('unurl/react')

const ReactComponentConnectStyle = connect(() => {
  // re-renders when url changes
})

const { useUrl } = require('unurl/react')

const ReactComponentEffectStyle = () => {
  const url = useUrl()
  // re-renders when url changes
}

API

const { url, searchParams, onChange, listen } = require('unurl')

url

A Proxy of new URL that fires onChange whenever a property is changed.

• @property {string} hostname A String containing the domain of the URL.
• @property {string} pathname A String containing an initial '/' followed by the path of the URL.
• ...URL#Properties

searchParams

searchParams but in an object-form with values parsed for easier consumption.

Querystring | Object | Remark -------------|-------------------|---------------- ?a=b | { a: 'b' } | key=value converted to { key: value } ?a=1 | { a: 1 } | JSON parsed (~~'1'~~ 1) ?a, ?a= | { a: true } | Existence of key inferred as value true ?a=1,b | { a: [1, 'b'] } | Comma-separated parsed as array

onChange

A function to register a callback that's fired whenever url is changed, or when listening to browser events.

• @param {function} callback Callback to fire when url changes
• @returns {function} unRegister Frees the callback from firing anymore

listen

Listen to browser events: click (on an <a> element), popstate, and hashchange to fire onChange.

• @param {object} [opts]
• @param {Boolean|Object} [opts.click={}] Listen to click events on all <a> elements. Will prevent if href is from the same (current) hostname. Options will be passed to addEventListener.
• @returns {function} removeListener Removes and frees the attached event listeners

React API

React-specific helper functions.

const { connect, useUrl } = require('unurl/react')

connect

Converts a React Component into one that re-renders whenever url changes.

• @param {ReactComponent|Function} component React Component or a function to wrap
• @returns {ReactComponent} component Wrapper Component that renders the above component

useUrl

A React Hook that updates whenever url changes.