Events

Page code can follow each search through the swc-* custom events the components dispatch. Each event bubbles through shadow roots (composed: true) and carries its payload on event.detail.

document.addEventListener('swc-post-search', (event) => {
  if (event.detail.outcome === 'ok') {
    console.log(event.detail.query.toString());
  }
});

Add listeners before the package loads. The root starts its first search as it connects, so a listener added after the import misses the first swc-pre-search.

Every event

Event	Fired by	detail fields	When
swc-pre-search	search-root	query, searchQuery, criteria, context, requestedBy	Before each search is sent.
swc-search-error	search-root	error, query, searchQuery, criteria, context, requestedBy	When a search fails. The search's swc-post-search follows.
swc-post-search	search-root	query, searchQuery, criteria, context, requestedBy, outcome	When a search settles. outcome is ok, error, or superseded.
swc-search-request	Every component that searches, or a page's own code	query, and searchPromise, which the root adds	When a component triggers a search. The root handles the event and stops its propagation, so it never reaches document.
swc-update-context	Every component that changes the search or view state	context, alreadyPublished	When a component publishes a changed context.
swc-post-facet-apply	The facet elements, search-applied-facets	key, value, clearApplied, context	When a facet value is applied or removed, as the search starts.
swc-post-clear-facet	The facet elements	key, context	When a facet's values are all removed, as the search starts.
swc-post-clear-facets	search-applied-facets	context	When every facet value is removed, as the search starts.
swc-component-search-results-rendered	search-results	component	Once the results are in the page, after each search, listing layout change, or mappings change.

The fields:

• query: the URL state searched, a URLSearchParams, without additionalParams.
• searchQuery: the parameters sent, with additionalParams.
• criteria: searchQuery parsed. For the fields of the parsed query, see Searching another API.
• context: the search context when the event fired.
• requestedBy: the element that asked for the search, a component or the root.
• key in the facet events: the facet's URL alias, not its key attribute.
• component: the search-results element.

event.data, event.context, and event.alreadyPublished are deprecated and will be removed in 2.0. event.data is the same object as event.detail, and the other two repeat the fields of swc-update-context.

When the facet events fire

swc-post-facet-apply, swc-post-clear-facet, and swc-post-clear-facets fire when the search starts, right after its swc-pre-search. When the search lands, its swc-post-search fires, with the facet as requestedBy.

Checking a facet option fires, in order:

1. swc-pre-search, with the facet as requestedBy
2. swc-post-facet-apply
3. swc-post-search
4. swc-component-search-results-rendered
5. swc-update-context with alreadyPublished: true

The context echo

After a search a component asked for lands, that component dispatches swc-update-context with alreadyPublished: true. The root has published that context already and does not merge it again. The echo is for listeners outside the root.

The event log here lists each event with its detail fields:

Requesting a search from page code

Page code triggers a search by dispatching swc-search-request, with the URL state to search, on the search-root or on any element inside it. The root runs the search, writes the page URL, and fires the usual events. The root sets detail.searchPromise on the event, for code that waits for the search:

const event = new CustomEvent('swc-search-request', {
  bubbles: true,
  composed: true,
  detail: {query: new URLSearchParams('q=soup')},
});
document.querySelector('search-root').dispatchEvent(event);
await event.detail.searchPromise;

The query replaces the URL state, so the search above has no facets, sort, or page. To keep the current state, start from the root's context.query. The Search Web Components elements send this event through getResults().

The Show soups button here is plain HTML. Its click dispatches swc-search-request with q=soup:

Which event to use

• A spinner: swc-pre-search and swc-post-search always come in pairs. The root also has the class is-loading while a search runs, and search-loading-indicator shows its children while a search runs.
• Analytics: swc-post-search with event.detail.outcome === 'ok'. event.detail.requestedBy names the element that searched.
• Errors: swc-search-error. For what the error carries, see Errors and outcomes.