atomic-color-facet

This is for:

Developer
Note

This component was introduced in version 1.0.4.

A facet is a list of values for a certain field occurring in the results, ordered using a configurable criteria (e.g., number of occurrences). An atomic-color-facet displays a facet of the results for the current query as colors.

Introduction

A facet allows users to drill down inside a result set by filtering the result to certain field values. A Color Facet presents its information in a visual way.

User Experience and Best Practices

Usage Notes

  • A color facet is best for placing emphasis on the visual aspect of a facet value.

  • The two available options to display the facet values are box and checkbox.

    • The box display option will present the facet values in a grid with a larger tile format.

    • The checkbox display option will present the values in a list with a smaller icon or color tile.

Guidelines

When the facet doesn’t have too many values to display and the text labels are short, it’s best practice to use the box display option.

When using an image instead of a color tile or icon, it’s best practice to use the box display.

Use Cases and Examples

In commerce, a user shopping for a t-shirt can select the colors they want using a color-faceted.

Reference

Don’t Lose Face with Facets

Wayfair implementation of a visual facet

Properties

Property Attribute Description Type Default

allowedValues

allowed-values

Specifies an explicit list of allowedValues in the Search API request. This list is in the form of a JSON string.

If you specify a list of values for this option, the facet only uses these values (if they are available in the current result set).

Example:

The following facet only uses the Contact, Account, and File values of the objecttype field. Even if the current result set contains other objecttype values, such as Message or Product, the facet does not use them.

<atomic-color-facet field="objecttype" allowed-values='["Contact","Account","File"]'></atomic-color-facet>

The maximum amount of allowed values is 25.

The default value is undefined, and the facet uses all available values for its field in the current result set.

string | string[]

'[]'

customSort

custom-sort

Identifies the facet values that must appear at the top, in this order. This parameter can be used in conjunction with the sortCriteria parameter.

Facet values not part of the customSort list will be sorted according to the sortCriteria.

Example:

The following facet will sort the Contact, Account, and File values at the top of the list for the objecttype field.

If there are more than these 3 values available, the rest of the list will be sorted using occurrences.

<atomic-color-facet field="objecttype" custom-sort='["Contact","Account","File"]' sort-criteria='occurrences'></atomic-color-facet>

The maximum amount of custom sort values is 25.

The default value is undefined, and the facet values will be sorted using only the sortCriteria.

string | string[]

'[]'

dependsOn

The required facets and values for this facet to be displayed. Examples:

<atomic-facet facet-id="abc" field="objecttype" ...></atomic-facet>

<!-- To show the facet when any value is selected in the facet with id "abc": -->
<atomic-color-facet
  depends-on-abc
  ...
></atomic-color-facet>

<!-- To show the facet when value "doc" is selected in the facet with id "abc": -->
<atomic-color-facet
  depends-on-abc="doc"
  ...
></atomic-color-facet>

{ [x: string]: string; }

{}

displayValuesAs

display-values-as

Whether to display the facet values as checkboxes (multiple selection) or boxes (multiple selection). Possible values are 'checkbox', and 'box'.

"box" | "checkbox"

'box'

facetId

facet-id

Specifies a unique identifier for the facet.

string | undefined

field (required)

field

The field whose values you want to display in the facet.

string

filterFacetCount

filter-facet-count

Whether to exclude the parents of folded results when estimating the result count for each facet value.

boolean

true

headingLevel

heading-level

The heading level to use for the heading over the facet, from 1 to 6.

number

0

injectionDepth

injection-depth

The maximum number of results to scan in the index to ensure that the facet lists all potential facet values. Note: A high injectionDepth may negatively impact the facet request performance. Minimum: 0 Default: 1000

number

1000

isCollapsed

is-collapsed

Specifies whether the facet is collapsed. When the facet is the child of an atomic-facet-manager component, the facet manager controls this property.

boolean

false

label

label

The non-localized label for the facet. Used in the atomic-breadbox component through the bindings store.

string

'no-label'

numberOfValues

number-of-values

The number of values to request for this facet. Also determines the number of additional values to request each time more values are shown.

number

8

resultsMustMatch

results-must-match

Specifies how a result must match the selected facet values. Allowed values: - atLeastOneValue: A result will match if at least one of the corresponding facet values is selected. - allValues: A result will match if all corresponding facet values are selected.

"allValues" | "atLeastOneValue"

'atLeastOneValue'

sortCriteria

sort-criteria

The sort criterion to apply to the returned facet values. Possible values are 'score', 'alphanumeric', 'alphanumericDescending', 'occurrences', alphanumericNatural', 'alphanumericNaturalDescending' and 'automatic'.

"alphanumeric" | "alphanumericDescending" | "alphanumericNatural" | "alphanumericNaturalDescending" | "automatic" | "occurrences" | "score"

'automatic'

tabsExcluded

tabs-excluded

The tabs on which this facet must not be displayed. This property should not be used at the same time as tabs-included.

Set this property as a stringified JSON array, e.g.,

 <atomic-timeframe-facet tabs-excluded='["tabIDA", "tabIDB"]'></atomic-timeframe-facet>

If you don’t set this property, the facet can be displayed on any tab. Otherwise, the facet won’t be displayed on any of the specified tabs.

string | string[]

'[]'

tabsIncluded

tabs-included

The tabs on which the facet can be displayed. This property should not be used at the same time as tabs-excluded.

Set this property as a stringified JSON array, e.g.,

 <atomic-timeframe-facet tabs-included='["tabIDA", "tabIDB"]'></atomic-timeframe-facet>

If you don’t set this property, the facet can be displayed on any tab. Otherwise, the facet can only be displayed on the specified tabs.

string | string[]

'[]'

withSearch

with-search

Whether this facet should contain a search box.

boolean

true

Shadow parts

Part Description

clear-button

The button that resets the actively selected facet values.

clear-button-icon

The clear button icon.

default-color-value

The default part name used to customize color facet values. Should be defined before dynamic parts.

facet

The wrapper for the entire facet.

label-button

The button that displays the label and allows to expand/collapse the facet.

label-button-icon

The label button icon.

matches-query

The highlighted query inside the matches labels.

more-matches

The label indicating there are more matches for the current facet search query.

no-matches

The label indicating there are no matches for the current facet search query.

placeholder

The placeholder shown before the first search is executed.

search-clear-button

The button to clear the search box of input.

search-highlight

The highlighted query inside the facet values.

search-icon

The search box submit button.

search-input

The search box input.

search-wrapper

The search box wrapper.

show-less

The show less results button.

show-more

The show more results button.

show-more-less-icon

The icons of the show more & show less buttons.

value-*

The dynamic part name used to customize a facet value. The * is a syntactical placeholder for a specific facet value. For example, if the component’s field property is set to 'filetype' and your source has a YouTubeVideo file type, the part would be targeted like this: atomic-color-facet::part(value-YouTubeVideo)…​.

value-box

The facet value when display is 'box'.

value-box-selected

The selected facet value when display is 'box'.

value-checkbox

The facet value checkbox, available when display is 'checkbox'.

value-checkbox-checked

The checked facet value checkbox, available when display is 'checkbox'.

value-checkbox-label

The facet value checkbox clickable label, available when display is 'checkbox'.

value-count

The facet value count, common for all displays.

value-label

The facet value label, common for all displays.

values

The facet values container.

CSS custom content

Name Description

--atomic-facet-boxes-gap

Gap value for facet values, when the display is 'box'

--atomic-facet-boxes-per-row

Number of facet values to display per row, when the display is 'box'

--atomic-facet-checkbox-size

Size of the checkbox.

--atomic-facet-color-boxes-gap

Gap value for facet values for the Color Facet , when the display is 'box'

--atomic-facet-color-boxes-per-row

Number of facet values for the Color Facet to display per row, when the display is 'box'

--atomic-facet-search-clear-icon-size

The size of the facet search clear icon.

--atomic-facet-search-icon-size

The size of the facet search icon.