buildListHref

src/lists/build-list-href.tsfunction

buildListHref()

buildListHref(list: ListDefinition<TParams, {}>, location: ListLocation, changes: Partial<ParamsState<TParams>>): string

Build a link to the list with some of its state changed.

• A key set to undefined in changes goes back to its default.
• The page returns to its default when any other param’s value actually changes — a page number means nothing in a different list — unless changes names page itself. Setting a param to the value it already holds keeps the page.
• Values equal to their default stay out of the URL, and an unreadable value in the current URL is dropped.
• Keys the list does not own are kept, ahead of the list’s own, which follow in declaration order. The hash is dropped.
• Commas are left unescaped, so sorts read sort=-publishedAt,title. Never compare raw query strings. toSearchParams(…).toString() evens out encoding (, against %2C) but not key order; to test whether the URL already shows a state, compare buildListHref(list, location, changes) with buildListHref(list, location), the current URL in canonical form.

buildListHref(articleList, { pathname: '/articles', search: '?page=3' }, { q: 'react' });
// '/articles?q=react'

Parameter	Type	Description
list	ListDefinition<TParams, {}>	The list, as defineList() returned it
location	ListLocation	The page’s path and current query
changes	Partial<ParamsState<TParams>>	The state to change; keys left out keep their current value

Returns — The path, with its query when there is one