Search Web Components

Appearance

Install ​

The npm package drupal-search-web-components puts Search Web Components on any page that can reach a search endpoint, with or without Drupal.

sh
npm install drupal-search-web-components

Import the elements ​

Importing the package entry registers every element:

js
import 'drupal-search-web-components';

To register only the elements a page uses, import each one by its path:

js
import 'drupal-search-web-components/dist/search-root/search-root.js';
import 'drupal-search-web-components/dist/search-input/search-input.js';
import 'drupal-search-web-components/dist/search-results/search-results.js';

A deep import must use a path listed in the package's exports map, with the .js extension. The map lists:

  • each element as dist/<tag>/<tag>.js, e.g., dist/search-sort/search-sort.js
  • dist/BaseSearchElement.js, dist/BaseFacetElement.js, dist/BaseDropdownElement.js, dist/SearchRequestError.js, and dist/types.js
  • search-web-components.min.js, custom-elements.json, and package.json

The entry has named exports for:

  • every element class, BaseSearchElement, BaseFacetElement, DropdownMixin, and SearchRequestError
  • the functions parseSearchCriteria, toSearchApiDecoupledParams, assertSearchResponseShape, and normalizeSearchResponse, and the context key searchContext
  • the types

Import a class by name, e.g., import {SearchRoot} from 'drupal-search-web-components'. A named import still runs the whole entry, so every element is registered, not only the one named.

The modules are plain ES modules, so a browser can also load them through an import map.

Without a build step ​

search-web-components.min.js is one module that defines every element and puts the classes on window.SearchWebComponents. Load it from the installed package, or from an npm CDN:

html
<script
  type="module"
  src="node_modules/drupal-search-web-components/search-web-components.min.js"
></script>
html
<script
  type="module"
  src="https://unpkg.com/drupal-search-web-components/search-web-components.min.js"
></script>

For a search page built this way, see the Quickstart.

On a Drupal page ​

Each component attaches the library search_web_components/components, so the bundle is on every page that has a component, and the bundle puts the classes on window.SearchWebComponents. JavaScript of your own that uses a class, e.g., a subclass of SearchRoot, takes it from there:

js
const {SearchRoot} = window.SearchWebComponents;
  • That JavaScript goes in a library of your own that depends on search_web_components/components, so it runs after the bundle.
  • Do not import the npm package on the same page. A second copy defines search-root again, and the browser throws an error because the tag is taken.
  • window.SearchWebComponents holds the entry's named exports except the types, which only the npm entry has, and under lit the template helpers a render() override needs: html, css, nothing, and unsafeHTML.

For the library definition and a subclass that uses it, see A subclass on a Drupal page.

Contributing ​

To work on Search Web Components itself, see Contributing.