Search Web Components

The Search Web Components module aims to make creating rich search experiences easy. It does this by providing a library of search web components that are powerful, decoupled, unopinionated, modern, composable, and easily integrated into layouts/templates. To do this the module builds on top of the endpoints provided by Decoupled Search API

Gone are the days of fighting with Views and Ajax to get a half working search that site owners are kinda okay with.

Checkout the components in Storybook

Checkout the Umami demo

Getting Started

1. Install this module and it's dependencies using composer or your preferred install method
2. Enable this module
3. Create/configure a Search Index
4. Configure a new Search API endpoint Configuration > Search and metadata > Search API Endpoints(/admin/config/search/search-api/endpoints)
5. Place the components on a page

With HTML

The components can be placed in a twig file like any other html just make sure that the search_web_components/components library is attached to the page and that the components are wrapped by a <search-root>. Checkout the source code for a sample page in Storybook.

With Blocks

The Search Web Components(search_web_components_block) submodule exposes each component as a block that can be placed via layout builder. When Two basic layouts are included in the Search Web Components: Layouts(search_web_components_layout) submodule that handles attaching the library and wrapping blocks in a <search-root> element.

Is This Ready For Prod?

It should be. While there is only an alpha release the architecture and existing components are largely stable. Unless a significant issue is found they should see minimal breaking changes between now and a stable release. Once there is some user feedback on the current functionality and tests cover most of the components a stable release will be tagged.

Why Decoupled?

Because decoupled makes it easier to render changes clientside which will(should) always be faster than making requests for HTML to a server. Search pages are an interactive experience, by decoupling from Drupal's theming layer we can create the interactions in the browser while still leveraging Search API and Drupal content.

The components in this library are truly decoupled and have no dependencies on Drupal. As long as the <search-root> can be pointed at a working Drupal Search API endpoint these components will work anywhere they are placed.

Why Web Components?

First, a brief explainer of what web components are. Web components are a set of standard web APIs that allow defining new custom HTML elements through javascript such as <my-element></my-element>. This custom component definition can encapsulate javascript, html, and css into a single entity for a browser to render.

So why web components? Because a search page is an interactive experience and interactivity on the web is best handled with javascript. Without clientside javascript to handle interactions, we've been relying on Ajax which is a slow and not great experience since it goes to Drupal's backend to render html, attach js, and attach css before updating a page. Web components provide a better way. A web component combines a known html structure with javascript scoped to the component making interactions easy and predictable.

Why Lit Over Vanilla JS?

The web component apis are fairly low level and a bit of a pain to work with. Lit provides a very lightweight abstraction on top of the spec that makes working with web components significantly easier. By lightweight I mean the entire component library for this module is currently 60kB.

Lit also provides a concept for shared state/context called Context based on a proposed addition to the web component spec. Context is what enables the search components to rerender when there is a new api response and to be sure they are all referencing the same set of data.

Why Not React/Angular/Other JS?

Web components are put onto a page as HTML, Drupal has a lot of really good ways to put HTML onto a page. With non web component based frameworks usually require fully building and deploying a search experience as an application. The resulting application often isn't composable meaning to make a change to one part of the search experience you need to rebuild and redeploy the whole application.

Also non web component based frameworks don't like playing with other frameworks where as web components are also increasingly being supported by frameworks so if you are working on a headless/decoupled site you can likely still use these components.

Can I theme these web components?

Yes, your Drupal theme will work on Search Web Components because it provides light DOM components only! Shadow DOM is an optional part of web components and is the thing that isolates web component styling from page styling. The components provided by the library intentionally turn off the shadow DOM making them light DOM components that respond to page styles.

Is there facet support?

Yep! Make sure to enable the facets and decoupled_search_api_facets modules, then configure some facets for your index before trying to place the web components.

Can I extend these components?

Yep! The components are written using TypeScript and the javascript is available as a npm package drupal-search-web-components.

Gotchas

Moving to a decoupled search means making sure that all the content needed to render the search page is in the index. This includes things like titles, urls, image urls, entity reference names instead of ids, etc.

It also includes all the content needed to render each search result for all content types in the index. Rendering results can be simplified by adding a Rendered HTML output (rendered_item) field to the index and configuring <search-results> to use the <search-result-element-rendered> element which will render the provided view mode for each result.

Known Areas for Improvement

• Accessibility: Components provided by this module aim to be accessible out of the box but there's always more to do. If you find an accessibility issue with a component please open an issue.
• Component availability: This module is just getting started so not all common component types or options are available yet. If you find something missing feel free to open a feature request.

Demo

Storybook

A storybook is published with each release that showcases all the web components available. The components in storybook are a good reference for available options and expected markup but use mock data so are not 100% functional.

Umami

An example module Umami: Search Web Components is available to show different ways Search Web Components can integrate into a site. If you are looking to add new components for your site the umami_search_components_adv module has several examples for how to do that.

Support options

Fund development Fund specific feature additions or help fund the day to day tasks required to maintain the module. Fund

Professional support Hire the me to help to ensure the success of your next project's search experience. I can review your plan, recommend solutions, and implement custom features. Contact Starting at $1000