Placing components from Twig

Every Search Web Components component is a single directory component, named search_web_components:<tag>, e.g., search_web_components:search-sort, that a Twig template can place with include. A search page in a template is a search_web_components:search-root with the components in its content slot, or one of the two search layout components provided by Search Web Components, with the components in its slots.

A search page in a template

This template renders the search page from Getting started, with the endpoint /api/search/content as the root's url:

{% set content %}
  {{ include('search_web_components:search-input', {labelText: 'Search'|t}, with_context = false) }}
  {{ include('search_web_components:search-sort', {type: 'select', labelText: 'Sort by'|t}, with_context = false) }}
  {{ include('search_web_components:search-result-summary') }}
  {{ include('search_web_components:facet-checkbox', {key: 'content_type'}, with_context = false) }}
  {{ include('search_web_components:search-results') }}
  {{ include('search_web_components:search-simple-pager') }}
  {{ include('search_web_components:search-no-results-message') }}
{% endset %}
{{ include('search_web_components:search-root', {
  url: '/api/search/content',
  defaultPerPage: '10',
  content: content,
}, with_context = false) }}

The components search through the search-root that contains them. A component placed outside a search 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.

Props

Props are the element's attributes, under the same camelCase names. For each attribute and the values it takes, see the component's page in Storybook. A prop left out takes the element's default.

Three props can override an endpoint setting with the component's own:

• sorts on search-sort overrides the endpoint's sort options with one {key, order, label, alias} object per option. key is the sort field, order is asc or desc, label is the text shown, and alias is the option's name in the page URL. For the alias, see Sort options.

  {{ include('search_web_components:search-sort', {
    type: 'list',
    labelText: 'Sort by'|t,
    sorts: [
      {key: 'search_api_relevance', order: 'desc', label: 'Relevance'|t},
      {key: 'title', order: 'asc', label: 'A-Z'|t},
    ],
  }, with_context = false) }}

• options on search-results-per-page overrides the endpoint's page sizes, and on search-results-switcher its listing layouts, with one {key, label} object per option.

  {{ include('search_web_components:search-results-per-page', {
    type: 'select',
    options: [{key: '10', label: '10'}, {key: '25', label: '25'}],
  }, with_context = false) }}

• mappings on search-results overrides the endpoint's result elements with result mappings as a JSON string, and resultField the match field. For the shape of the JSON, see The mappings shape.

  {{ include('search_web_components:search-results', {
    resultField: 'type',
    mappings: '[{"element": "recipe-card", "keys": ["recipe"], "settings": {}}, {"element": "search-result-element-rendered", "keys": ["default"], "settings": {"field": "rendered_item"}}]',
  }, with_context = false) }}

The layout components

search_web_components:search-layout-one-column and search_web_components:search-layout-two-column render a search-root with their slots inside it. Each slot takes a render array: one component, a list of components, or a component with content in its own slot. For the slot names and the layout props, see Drupal Canvas.

{{ include('search_web_components:search-layout-two-column', {
  url: '/api/search/content',
  defaultPerPage: '10',
  topOne: {
    '#type': 'component',
    '#component': 'search_web_components:search-input',
  },
  sidebarOne: [
    {
      '#type': 'component',
      '#component': 'search_web_components:facet-checkbox',
      '#props': {key: 'content_type'},
    },
    {
      '#type': 'component',
      '#component': 'search_web_components:facet-checkbox',
      '#props': {key: 'tags'},
    },
  ],
  mainOne: {
    '#type': 'component',
    '#component': 'search_web_components:search-loading-indicator',
    '#slots': {content: {'#markup': '<p>Loading</p>'}},
  },
  mainTwo: {
    '#type': 'component',
    '#component': 'search_web_components:search-results',
  },
}, with_context = false) }}

Attributes

To add a class or another attribute to the element, pass attributes:

{{ include('search_web_components:search-sort', {
  type: 'select',
  attributes: create_attribute({class: ['recipe-sort']}),
}, with_context = false) }}

An attribute can have the name of a prop, e.g., labelText. When the include passes the prop as well as the attribute, the prop's value is used and the attribute's is dropped.

Translated text

A component placed from Twig shows the element's English text until the prop is set. Pass translated text with |t, e.g., ariaLabelText: 'Pages'|t on search_web_components:search-simple-pager.

The JavaScript

Each component attaches the Search Web Components library itself.

To change the markup of a component or the props of one placed block, see Customizing in Drupal code.