The URL holds the search

Each search writes its keywords, facets, sort, page size, and results page to the page URL. A visitor can bookmark or share the URL. The browser's Back and Forward step through the searches.

Search, check a category, sort, and change the results page here, and the readout above the search shows the URL of each search:

Parameters

Parameter	Holds	Example
q	The keywords.	?q=soup
page	The results page, counted from 0. Left out on the first results page, to keep the URL short.	?page=1 is the second results page.
limit	The page size. Left out when it is the root's defaultPerPage.	?limit=25
sort	A sort field, or a sort option's alias.	?sort=title
order	The sort direction, asc or desc. Not used with an alias, since the alias names an option with a direction.	?order=desc
f[<alias>]	A facet value, under the facet's URL alias. Repeated for each value.	?f[category]=Desserts&f[category]=Soups

When q, page, limit, sort, or order is repeated, the last value is used.

The request to a Search API Decoupled endpoint sends each facet value as f[0]=category:Desserts, f[1]=category:Soups, and so on, while the page URL keeps the f[<alias>] form of the table. The request always names the page size as limit, so the endpoint's own default does not apply.

Sort

search-sort and the endpoint read the sort in the URL in this order:

The URL has	The sort is	Example
sort and order	The option with that field and direction. When no option has the field, sort is read as an alias and order is ignored.	?sort=title&order=asc sorts by title, ascending.
sort only	The option with that alias. When no option has that alias, the field in the default direction.	?sort=quickest when an option has that alias. ?sort=title when none does.
order only	The default field in that direction.	?order=desc
Neither	The option marked default. With no option marked, the response's default_sort and default_sort_order.	?q=soup

When a visitor picks an option, search-sort writes:

The option	The URL gets	Example
Has an alias and is the default	No sort and no order.	?q=soup
Has an alias and is not the default	sort=<alias>.	?sort=quickest
Has no alias	sort and order. The sort is left out when it is the response's default_sort, and the order when it is the response's default_sort_order.	?sort=title&order=asc

The default option is the one marked default. With no option marked, it is the option whose key and order are the response's default_sort and default_sort_order.

What resets the results page

Each of these searches from the first results page. The rest of the search is kept, except where noted:

• a new keyword, or a cleared one, in search-input. Without keepFilters, the new search keeps only q.
• a facet value applied or removed, a facet's reset button, or a button in search-applied-facets.
• a new page size.
• a new sort.
• a search-did-you-mean suggestion.

A start versus a curated filter

search-root has two ways to shape a search before the visitor touches it:

• A start. A query string on the url attribute, e.g., url="/api/search/content?q=coffee&f[type]=recipe", seeds the first search when the page URL has none of the search parameters above. The start is written to the page URL and becomes ordinary state. It shows as applied. The visitor can change or clear it.
• A curated filter. additionalParams="?f[type]=recipe" is added to every search and never written to the page URL. The visitor cannot remove it. Facet values in additionalParams are never shown as options or as applied. A facet whose options are all curated renders nothing. A field filter the endpoint accepts, e.g., ?type=recipe, is sent the same way, and a comma-separated value, e.g., ?type=a,b, matches either value.

The endpoint's own Filters scope the endpoint to a subset of content on the server, for every page that searches it. additionalParams scopes one search root, in the browser.

Attributes the root reads on every search

The root reads url, additionalParams, defaultPerPage, and noPageUrlUpdate for every search, whether the root or a component started it. After a change to any of these attributes, the next search uses the new value.

defaultResultDisplay and dialogBreakpoint are copied into the context by the first search. A later change to either attribute replaces the value in the context, including a listing layout the visitor picked.

Keeping the page URL unchanged

noPageUrlUpdate on the root stops both directions:

• searches do not write the page URL
• the root ignores the page URL, so a page opened with ?q=soup searches without the keyword, and Back and Forward do not search.

To read the page URL but never write it, override _updateHistory() with an empty body:

class QuietSearchRoot extends SearchRoot {
  override _updateHistory() {}
}
customElements.define('quiet-search-root', QuietSearchRoot);

_updateHistory(query, initialSearch) writes the searched URL state to the page URL. The first search that writes replaces the current history entry. Each later search pushes an entry when the query string changed. Override it to change that.

One root owns the URL

Every root on a page reads and writes the same location.search. On a page with two roots, set noPageUrlUpdate on every root but one.