atomic-search-box

This is for:

Developer

In this article

Introduction
User Experience and Best Practices
Properties
Slots
Shadow Parts

The atomic-search-box component creates a search box with built-in support for suggestions.

Go to the interactive example

Introduction

The Search Box component is the core of a search page, allowing the user to type and submit a query. There is built-in support for query suggestions in the Search Box component.

User Experience and Best Practices

Guidelines

It’s important to have it visible and clear to the user, best practices suggest that it should be in the top-center or upper-right section.

Reference

Search Best Practices Part 1 - The Search Box

Search: Visible and Simple

Properties

Property Attribute Description Type Default

Property	Attribute	Description	Type	Default
`clearFilters`	`clear-filters`	Whether to clear all active query filters when the end user submits a new query from the search box. Setting this option to "false" is not recommended & can lead to an increasing number of queries returning no results.	`boolean`	`true`
`disableSearch`	`disable-search`	Whether to prevent the user from triggering searches and query suggestions from the component. Perfect for use cases where you need to disable the search conditionally. For the specific case when you need to disable the search based on the length of the query, refer to {@link minimumQueryLength}.	`boolean`	`false`
`enableQuerySyntax`	`enable-query-syntax`	Whether to interpret advanced Coveo Cloud query syntax in the query. You should only enable query syntax in the search box if you have good reasons to do so, as it requires end users to be familiar with Coveo Cloud query syntax, otherwise they will likely be surprised by the search box behaviour. When the `redirection-url` property is set and redirects to a page with more `atomic-search-box` components, all `atomic-search-box` components need to have the same `enable-query-syntax` value.	`boolean`	`false`
`minimumQueryLength`	`minimum-query-length`	The minimum query length required to enable search. For example, to disable the search for empty queries, set this to `1`.	`number`	`0`
`numberOfQueries`	`number-of-queries`	The amount of queries displayed when the user interacts with the search box. By default, a mix of query suggestions and recent queries will be shown. You can configure those settings using the following components as children: - atomic-search-box-query-suggestions - atomic-search-box-recent-queries	`number`	`8`
`redirectionUrl`	`redirection-url`	Defining this option makes the search box standalone (see Use a Standalone Search Box(https://docs.coveo.com/en/atomic/latest/usage/ssb/). This option defines the default URL the user should be redirected to, when a query is submitted. If a query pipeline redirect is triggered, it will redirect to that URL instead (see query pipeline triggers).	`string \| undefined`
`suggestionDelay`	`suggestion-delay`	The delay for suggestion queries on input, in milliseconds. The suggestion request will be delayed until the end user stops typing for at least the specified amount of time. This delay is used to avoid sending too many requests to the Coveo Platform when the user is typing, as well as reducing potential input lag on low end devices. A higher delay will reduce input lag, at the cost of suggestions freshness.	`number`	`0`
`suggestionTimeout`	`suggestion-timeout`	The timeout for suggestion queries, in milliseconds. If a suggestion query times out, the suggestions from that particular query won’t be shown.	`number`	`400`
`textarea`	`textarea`	Whether to render the search box using a textarea element. The resulting component will expand to support multi-line queries. When customizing the dimensions of the textarea element using the `"textarea"` CSS part, it is important to also apply the styling to its container’s ::after pseudo-element as well as the `"textarea-spacer"` part. The buttons within the search box are likely to need adjusting as well. Example: `<style> atomic-search-box::part(textarea), atomic-search-box::part(textarea-expander)::after, atomic-search-box::part(textarea-spacer) { font-size: x-large; } atomic-search-box::part(submit-button-wrapper), atomic-search-box::part(clear-button-wrapper) { padding-top: 0.75rem; } </style>` NB: The textarea functionality will be enforced on the next major version of Atomic (3.0.0)	`boolean`	`false`

clearFilters

clear-filters

Whether to clear all active query filters when the end user submits a new query from the search box. Setting this option to "false" is not recommended & can lead to an increasing number of queries returning no results.

boolean

true

disableSearch

disable-search

Whether to prevent the user from triggering searches and query suggestions from the component. Perfect for use cases where you need to disable the search conditionally. For the specific case when you need to disable the search based on the length of the query, refer to {@link minimumQueryLength}.

boolean

false

enableQuerySyntax

enable-query-syntax

Whether to interpret advanced Coveo Cloud query syntax in the query. You should only enable query syntax in the search box if you have good reasons to do so, as it requires end users to be familiar with Coveo Cloud query syntax, otherwise they will likely be surprised by the search box behaviour.

When the redirection-url property is set and redirects to a page with more atomic-search-box components, all atomic-search-box components need to have the same enable-query-syntax value.

boolean

false

minimumQueryLength

minimum-query-length

The minimum query length required to enable search. For example, to disable the search for empty queries, set this to 1.

number

0

numberOfQueries

number-of-queries

The amount of queries displayed when the user interacts with the search box. By default, a mix of query suggestions and recent queries will be shown. You can configure those settings using the following components as children: - atomic-search-box-query-suggestions - atomic-search-box-recent-queries

number

8

redirectionUrl

redirection-url

Defining this option makes the search box standalone (see Use a Standalone Search Box(https://docs.coveo.com/en/atomic/latest/usage/ssb/).

This option defines the default URL the user should be redirected to, when a query is submitted. If a query pipeline redirect is triggered, it will redirect to that URL instead (see query pipeline triggers).

string | undefined

suggestionDelay

suggestion-delay

The delay for suggestion queries on input, in milliseconds.

The suggestion request will be delayed until the end user stops typing for at least the specified amount of time.

This delay is used to avoid sending too many requests to the Coveo Platform when the user is typing, as well as reducing potential input lag on low end devices. A higher delay will reduce input lag, at the cost of suggestions freshness.

number

0

suggestionTimeout

suggestion-timeout

The timeout for suggestion queries, in milliseconds. If a suggestion query times out, the suggestions from that particular query won’t be shown.

number

400

textarea

Whether to render the search box using a textarea element. The resulting component will expand to support multi-line queries. When customizing the dimensions of the textarea element using the "textarea" CSS part, it is important to also apply the styling to its container’s ::after pseudo-element as well as the "textarea-spacer" part. The buttons within the search box are likely to need adjusting as well.

Example:

<style>
  atomic-search-box::part(textarea),
  atomic-search-box::part(textarea-expander)::after,
  atomic-search-box::part(textarea-spacer) {
    font-size: x-large;
  }

  atomic-search-box::part(submit-button-wrapper),
  atomic-search-box::part(clear-button-wrapper) {
    padding-top: 0.75rem;
  }
</style>

NB: The textarea functionality will be enforced on the next major version of Atomic (3.0.0)

boolean

false

Slots

Slots let you write custom HTML at a specific place inside a web component.

Slot Description

Slot	Description
`default`	The default slot where you can add child components to the search box.

default

The default slot where you can add child components to the search box.

Shadow Parts

Part Description

Part	Description
`active-suggestion`	The currently active suggestion.
`clear-button`	The button to clear the search box of input.
`clear-icon`	The clear button’s icon.
`input`	The search box input.
`instant-results-item`	An instant result rendered by an `atomic-search-box-instant-results` component.
`instant-results-show-all`	The clickable suggestion to show all items for the current instant results search rendered by an `atomic-search-box-instant-results` component.
`instant-results-show-all-button`	The button inside the clickable suggestion from the `atomic-search-box-instant-results` component.
`loading`	The search box loading animation.
`query-suggestion-content`	The contents of a suggestion from the `atomic-search-box-query-suggestions` component.
`query-suggestion-icon`	The icon of a suggestion from the `atomic-search-box-query-suggestions` component.
`query-suggestion-item`	A suggestion from the `atomic-search-box-query-suggestions` component.
`query-suggestion-text`	The text of a suggestion from the `atomic-search-box-query-suggestions` component.
`recent-query-clear`	The "clear" text of the clear button above suggestions from the `atomic-search-box-recent-queries` component.
`recent-query-content`	The contents of a suggestion from the `atomic-search-box-recent-queries` component.
`recent-query-icon`	The icon of a suggestion from the `atomic-search-box-recent-queries` component.
`recent-query-item`	A suggestion from the `atomic-search-box-recent-queries` component.
`recent-query-text`	The text of a suggestion from the `atomic-search-box-recent-queries` component.
`recent-query-text-highlight`	The highlighted portion of the text of a suggestion from the `atomic-search-box-recent-queries` component.
`recent-query-title`	The "recent searches" text of the clear button above suggestions from the `atomic-search-box-recent-queries` component.
`recent-query-title-content`	The contents of the clear button above suggestions from the `atomic-search-box-recent-queries` component.
`recent-query-title-item`	The clear button above suggestions from the `atomic-search-box-recent-queries` component.
`submit-button`	The search box submit button.
`submit-icon`	The search box submit button’s icon.
`suggestion`	A suggested query correction.
`suggestion-divider`	An item in the list that separates groups of suggestions.
`suggestion-with-query`	An item in the list that will update the search box query.
`suggestions`	A list of suggested query corrections on each panel.
`suggestions-double-list`	The wrapper that contains 2 suggestion lists.
`suggestions-left`	A list of suggested query corrections on the left panel.
`suggestions-right`	A list of suggested query corrections on the right panel.
`suggestions-single-list`	The wrapper that contains 1 suggestion list.
`suggestions-wrapper`	The wrapper that contains suggestion panels.
`textarea-spacer`
`wrapper`	The search box wrapper.

active-suggestion

The currently active suggestion.

clear-button

The button to clear the search box of input.

clear-icon

The clear button’s icon.

input

The search box input.

instant-results-item

An instant result rendered by an atomic-search-box-instant-results component.

instant-results-show-all

The clickable suggestion to show all items for the current instant results search rendered by an atomic-search-box-instant-results component.

instant-results-show-all-button

The button inside the clickable suggestion from the atomic-search-box-instant-results component.

loading

The search box loading animation.

query-suggestion-content

The contents of a suggestion from the atomic-search-box-query-suggestions component.

query-suggestion-icon

The icon of a suggestion from the atomic-search-box-query-suggestions component.

query-suggestion-item

A suggestion from the atomic-search-box-query-suggestions component.

query-suggestion-text

The text of a suggestion from the atomic-search-box-query-suggestions component.

recent-query-clear

The "clear" text of the clear button above suggestions from the atomic-search-box-recent-queries component.

recent-query-content

The contents of a suggestion from the atomic-search-box-recent-queries component.

recent-query-icon

The icon of a suggestion from the atomic-search-box-recent-queries component.

recent-query-item

A suggestion from the atomic-search-box-recent-queries component.

recent-query-text

The text of a suggestion from the atomic-search-box-recent-queries component.

recent-query-text-highlight

The highlighted portion of the text of a suggestion from the atomic-search-box-recent-queries component.

recent-query-title

The "recent searches" text of the clear button above suggestions from the atomic-search-box-recent-queries component.

recent-query-title-content

The contents of the clear button above suggestions from the atomic-search-box-recent-queries component.

recent-query-title-item

The clear button above suggestions from the atomic-search-box-recent-queries component.

submit-button

The search box submit button.

submit-icon

The search box submit button’s icon.

suggestion

A suggested query correction.

suggestion-divider

An item in the list that separates groups of suggestions.

suggestion-with-query

An item in the list that will update the search box query.

suggestions

A list of suggested query corrections on each panel.

suggestions-double-list

The wrapper that contains 2 suggestion lists.

suggestions-left

A list of suggested query corrections on the left panel.

suggestions-right

A list of suggested query corrections on the right panel.

suggestions-single-list

The wrapper that contains 1 suggestion list.

suggestions-wrapper

The wrapper that contains suggestion panels.

textarea-spacer

wrapper

The search box wrapper.