Search Web Components

Appearance

Concepts ​

A search is a search-root with components inside it, and a page can hold more than one. The root runs every search. The components show its state and trigger new searches.

The root and its components ​

  • search-root sends each search to the endpoint in its url attribute and keeps the page URL in step with the search. For how the page URL holds the search, see The URL holds the search.
  • The root shares a context with every component inside it. Each component renders from the context, which holds:
    • query: the URL state searched
    • response: the latest response
    • loading: whether a search is running
    • view state, e.g., resultDisplay, the listing layout shown.
  • A component that changes the search, e.g., a facet or the pager, calls getResults(query), which dispatches swc-search-request with the new URL state, and the root runs that search.
  • A component that changes only view state, e.g., search-results-switcher, publishes the changed context with swc-update-context. The root shares it with every component.
  • Components render into the light DOM, not a shadow root, so the page's CSS styles them. For the classes to style, see Styling.

Place every component inside a search-root. A component outside a root is not connected to a search and does nothing. The exception is search-box, which sends the visitor to a search page from anywhere, e.g., a header.

A search, step by step ​

  1. A search starts when a component asks the root, when the root connects, or when the visitor uses the browser's Back or Forward.
  2. The root publishes the requested URL state with loading: true. The root has the class is-loading until the search settles. search-results has aria-busy="true" for the same time.
  3. swc-pre-search fires on the root.
  4. The root builds the request, sends it, and maps the response, through _buildSearchRequest(), _fetchSearchResponse(), and _mapSearchResponse(). To search an API other than a Search API Decoupled endpoint, override them, see Searching another API.
  5. The root publishes the response, writes the page URL, and sets the class has-results, no-results, or search-error.
  6. swc-post-search fires on the root with outcome, which is ok or error, and requestedBy, the element that asked for the search.
  7. The components render the new response.

A search that fails clears the results and fires swc-search-error before swc-post-search. A search that a newer one replaces before it lands ends with swc-post-search and outcome: 'superseded'. Its response is discarded. For every event, see Events.

Search, check a content type, or change the results page here, and the event log lists each event with its detail fields:

Before the first response ​

Until the first response lands, the components that show response data, e.g., the results, facets, sort, and pager, render nothing.

search-loading-indicator shows its children while a search runs. With showOnFirstLoad, the indicator shows its children from the first paint until the first search settles, so the page can show a spinner instead of an empty space. In this story each search takes 1.5 seconds: