mattias-persson/url-parameters

A package to help you easily manage url parameters with browser history support and listening for changes.

url-parameters

Easily manage and listen for changes in query parameters, with full support for the browser history API.

Installation

npm install url-parameters --save

yarn add url-parameters

Usage

import url from 'url-parameters';

// Enable the URL listener. This will be triggered on page load and every time a URL parameter changes.
// You can use onChange.queryParams and onChange.queryString to access
// the URL parameters as an object or string.
url.enable(onChange => {
  console.log(onChange.queryParams); // object
  console.log(onChange.queryString); // string
});

Disabling Push State

You can disable the Push State by setting the second parameter to false when enabling the url listener:

url.enable(onChangeCallback, false);

This will add a # before the parameters in the URL and will prevent a page reload when the parameters are changed.

Modifying parameters and their values

All of these methods will trigger the listener callback in the enable() method demonstrated above which provides the updated parameters as an object and as the full query string.

// Add or update a single parameter value.
url.set('param', 'value')

// Add ?param=value if it's not already present. Remove the parameter if it is already present.
url.toggle('param', 'value')

// Toggle a value on the parameter. If the value already exists on the parameter it will be removed.
// If multiple values are present they will become a comma separated string.
url.toggleValue('param', 'value')

// Replace any current query string with the provided list of parameters.
url.apply('param=value&param2=value2')
url.apply({param: 'value', param2: 'value2'})

// Replace a set of parameter values. Will add non-existent parameters.
url.replace({param1: value1, param2: value2})

// Remove a parameter.
url.remove('param')

// Clear all parameters from the URL.
url.clear()

Accessing parameters and their values directly

// Returns the value of param or null if param is not present. 
url.get('param')

// Returns the value of param or 'default' if param is not present. 
url.get('param', 'default') 

// Check if a parameter contains a value, for example in a comma separated list of values.
url.containsValue('param', 'value')

// Returns the full query string.
url.getQueryString()

// Returns the URL parameters as an object.
url.getParams()

url-parameters's Issues

Handle lonely backslash in url.get tp avoid SyntaxError: JSON.parse: unterminated string error

Hi!

There seems to be an issue with line https://github.com/mattias-persson/url-parameters/blob/master/index.js#L162 which leads to SyntaxError when a url contains parameters that includes a \ character without any subsequent characters, e.g. http://example.com/#?search=\.

// on visiting the http://example.com/#?search=\ url the following happens
// in Url.prototype.getParams function
var search = "search=%5C"
// this gets decoded in the following function
return JSON.parse('{"' + decodeURI(search).replace(/"/g, '\\"').replace(/&/g, '","').replace(/=/g,'":"') + '"}');
// however this is not valid since the result is this
return JSON.parse("{"search":"\"}")
// which is not valid JSON and results in SyntaxError: JSON.parse: unterminated string

This might just be an edge case which I happened to come across.

Unexpected token export with with current version 1.6.1

Hi Mattias,
This lib looks very promising!
Unfortunately I get this error with the current version 1.6.1 in a react project - any idea where it comes from?
Might have to do with SSR...

｢hot｣: webpack: Compiling Done
/Users/achim/projects/hifi-studio-client/node_modules/url-parameters/index.js:168
export default new Url();
^^^^^^

SyntaxError: Unexpected token export
    at createScript (vm.js:80:10)
    at Object.runInThisContext (vm.js:139:10)
    at Module._compile (module.js:616:28)
    at Object.Module._extensions..js (module.js:663:10)
    at Module.load (module.js:565:32)
    at tryModuleLoad (module.js:505:12)
    at Function.Module._load (module.js:497:3)
    at Module.require (module.js:596:17)
    at require (internal/module.js:11:18)
    at eval (webpack-internal:///url-parameters:1:18)

Thanks in advance and all the best,
Achim