Guide: Adding URL parameter support

Many of our tasks involve supporting URL query parameters by setting and using them. This helps create unique, shareable URLs for the same page, particularly ones with sorting and filtering options.

Libraries

For the best coding and debugging experience, you should familiarize yourself with these libraries and functions:

• React Router, especially:
  • the useHistory and useLocation hooks
  • the history and location objects
  • history.push() and history.replace() functions and their differences.
• query-string, especially:
  • the .parse() and .stringify() functions
  • parse options like parseNumbers and parseBooleans
  • support for multiple instances of the same key (see second example here)
• JavaScript, especially:
  • ... operator
  • delete operator
  • Array.prototype.filter()

Common functions

Most setting/clearing/pruning of query params will look the same. Consider reusing these functions in the pages you need them:

setParam

Generically sets the given URL parameter key to the given val. Creates a history entry.

const setParam = (key, val) => {
  history.push({
    search: queryString.stringify({...params, [key]: val})
  });
}

clearParam

Generically clears the given URL parameter key to the given val. Creates a history entry.

const clearParam = (key) => {
  delete params[key];
  history.push({search: queryString.stringify(params)});
}

pruneParam

Generically clears the given URL parameter key to the given val. Replaces the current history entry.

const pruneParam = (key) => {
  delete params[key];
  history.replace({search: queryString.stringify(params)});
}

Basic Steps

1. Parse the URL parameters. You may want to specify options.

const history = useHistory();
const location = useLocation();
const params = queryString.parse(location.search);

2. Validate the parameter key/value you're working with, e.g. by checking its type and/or whether it's in a set of values.

3. If the parameter value is invalid, prune the parameter key from the URL query string by calling pruneParam(key) or by defining your own custom pruning function. Note that this step should replace the current history entry (so that users don't click back to a page with bad parameters).

4. If the setParam(key, val) and clearParam(key) functions aren't enough for wherever the URL parameter key/value needs to be updated, define your own custom updater function that can be used as a callback. E.g.

// Parse params...
const selectedIndex = params.selectedIndex;
// Validate selectedIndex...

const onSelectItem = (index) => {
  if (index === selectedIndex) {
    clearParam('selectedIndex');
  } else {
    setParam('selectedIndex', index);
  }
}

5. Use the parameter key/value and its updater function wherever needed. You will likely need to define wrapper functions around them if it doesn't make sense for a child component to understand query parameters. E.g.

const setFoo = (e) => setParam('foo', e.target.value);

return (
  {/* ... */}
    <Dropdown onChange={setFoo}>
  {/* ... */}
)