The response

A Search API Decoupled endpoint sends the response in this shape, and the components read it to render the results, the facets, and the sort, page size, and layout options. A search-root subclass that searches another API maps that API's response to this shape, see Searching another API. The package exports the type as SearchResponseType.

Required keys

Key	Holds
search_results	The results on the current results page. Each result has an id and a title, plus the fields its result element reads.
search_results_count	The total number of results of the search, not the number on the page.
search_results_page	The results page, counted from 0.
search_results_pages	The number of results pages.
search_results_per_page	The page size.
facets	One entry per facet. An empty list when the search has no facets. For what each entry holds, see Facet entries.

A response that misses one of these keys causes the search to fail: swc-search-error fires and the components show no results. A number key that holds no number causes the same failure. A number sent as a string, e.g., "10", is read as the number.

Optional keys

Key	Read by	Holds	Component attribute that overrides it
default_sort, default_sort_order	search-sort	The field and direction the endpoint sorts by when the URL names no sort.	none
took	search-result-summary	The search time in milliseconds, shown in seconds by the @time token.	none
swc_sorts	search-sort	The sort options.	sorts
swc_page_sizes	search-results-per-page	The page sizes.	options
swc_displays	search-results-switcher	The listing layouts.	options
swc_results	search-results	The match field and the result element mappings, or null when the endpoint has none.	resultField and mappings
swc_spellcheck	search-did-you-mean	The spelling suggestion. The element shows collatedSuggestion.	none

Option shapes

• Page sizes, in swc_page_sizes and the options attribute of search-results-per-page: {key, label}, with the page size as a string in key, e.g., {"key": "25", "label": "25 per page"}. A number in key never matches the page size in use, so no option is marked as selected.
• Listing layouts, in swc_displays and the options attribute of search-results-switcher: {key, label}, with the listing layout key in key, e.g., {"key": "grid", "label": "Grid"}.
• Sort options, in swc_sorts and the sorts attribute of search-sort: {key, order, label, alias?, default?}, e.g., {"key": "title", "order": "asc", "label": "A-Z", "alias": "title-asc"}.
  • key is the sort field and order is asc or desc.
  • alias names the option in the page URL. For how the URL reads a sort, see Sort.
  • default: true marks the option used when the URL names no sort.

The mappings shape

swc_results holds the match field and the mappings:

{
  "field": "type",
  "mappings": [
    {"keys": ["recipe"], "element": "recipe-card-result", "settings": {}},
    {"keys": ["default", "default-grid"], "element": "search-result-element-rendered", "settings": {"field": "rendered_item"}}
  ]
}

• field is the match field, the result field whose value picks the mapping. The resultField attribute overrides it.
• keys lists values of the match field. A value followed by a hyphen and a listing layout key, e.g., recipe-grid, matches only in that listing layout. default matches every value.
• element is the tag of the element that renders the result.
• settings reaches that element as its settings property.

The mappings attribute of search-results takes the same list. For how a result finds its mapping, see Custom result elements.

Facet entries

Each entry of facets drives the facet component whose key attribute matches its key:

Field	Used for
key	Matched against the component's key attribute.
label, count	The facet's label and its number of options. A facet with a count of 0 renders nothing.
settings.url_alias	The facet's name in f[...] URL parameters, and its key in criteria.facets.
settings.widget	The widget settings below. Send {} to configure the component with attributes only.
settings.show_title, settings.show_only_one_result	The widget settings below.
active_values, results[].active	Which options render as applied.
results[]	The options: key, label, count, children (a list, empty for none), in_active_trail, children_expanded.

The widget settings in the response and the attributes they stand for:

In the response	Component attribute
settings.show_title	showLabel
settings.show_only_one_result	showOnlyOneResult
settings.widget.show_numbers	showCount
settings.widget.showReset, resetText, collapsible, closed, showCountInCollapseLabel	The attribute of the same name.
settings.widget.soft_limit.limit, .less_label, .more_label	softLimit, softLimitLessLabel, softLimitMoreLabel
settings.widget.useRadios	useRadios on facet-checkbox
settings.widget.selectLabel	selectLabel on facet-dropdown
settings.widget.htmlSelectLabel, required, multipleSelect	The attribute of the same name on facet-dropdown-html.

Where a setting comes from

Setting	Components	Where it comes from
Sort options	search-sort	swc_sorts in the response, unless the sorts attribute is set.
Page sizes	search-results-per-page	swc_page_sizes in the response, unless the options attribute is set.
Listing layouts	search-results-switcher	swc_displays in the response, unless the options attribute is set.
Result elements	search-results	swc_results in the response, unless the mappings or the resultField attribute is set. Each attribute overrides its own part.
Facet widget settings	facet-checkbox, facet-button, facet-dropdown, facet-dropdown-html	The facet's settings in the response. The attribute applies to a setting the response leaves out, and with preferAttributes to every setting. The Drupal module sends show_title and the boolean widget settings, e.g., show_numbers, only when checked, so an attribute can turn one on, and sends show_only_one_result always, so showOnlyOneResult applies only with preferAttributes.

The two facets here have the same attributes. The left one is on an endpoint that sends no widget settings, so it renders from its attributes alone: a label and the options. The right one takes its widget settings from the response: counts, a reset button, and one option at a time.