atomic-category-facet

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-category-facet displays a facet of values in a browsable, hierarchical fashion.

Introduction

A facet allows users to drill down inside a result set by filtering the result to certain field values. Category Facets are browsable facets that display values in a hierarchical fashion, narrowing the available options through offering alternative starting points and sub-categories.

The Category Facet is especially useful when making fundamental decisions on a starting point in a search or browsing session. For example, if the starting point was Clothing, available options to choose from might include t-shirts, sweaters, brands, sales, new arrivals, etc. Each one of those options would then offer a new list of surrogate categories.

Best Practices

Usage Notes

  • A Category Facet requires a formatted multi-value field that’s formed in a hierarchical like this: clothing; clothing|sale; clothing|sale|shoes; clothing|sale|shoes|kids; clothing|sale|shoes|kids|sneakers;. The facet will determine the filter to apply based on the current selected path of values. This can offer a powerful navigational experience, quickly leading a user to relevant results.

  • It’s only possible to select one value at a time in a category facet. This is because they’re meant to ease navigation through their hierarchically organized content, as opposed to applying multiple hierarchical filters.

Guidelines

It’s best practice to have hierarchies at five levels or less in depth.

Use Cases and Examples

In a commerce website, a user may want to start browsing by the category Men, and then narrow their results to Bottoms, then further to Pants, etc. Instead of selecting the facet value directly, this allows them to navigate hierarchically and determine the right starting point.

Properties

Property Attribute Description Type Default

basePath

base-path

The base path shared by all values for the facet, separated by commas.

string | undefined

delimitingCharacter

delimiting-character

The character that separates values of a multi-value field.

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-category-facet
  depends-on-abc
  ...
></atomic-category-facet>
<!-- To show the facet when value "doc" is selected in the facet with id "abc": -->
<atomic-category-facet
  depends-on-abc="doc"
  ...
></atomic-category-facet>

{ [x: string]: string; }

{}

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

filterByBasePath

filter-by-base-path

Whether to use basePath as a filter for the results.

boolean

true

filterFacetCount

filter-facet-count

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

boolean

true

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

number

1000

isCollapsed

is-collapsed

Specifies if the facet is collapsed.

boolean

false

label

label

The non-localized label for the facet.

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

sortCriteria

sort-criteria

The sort criterion to apply to the returned facet values. Possible values are 'alphanumeric' and 'occurrences'.

"alphanumeric" | "occurrences"

'occurrences'

withSearch

with-search

Whether this facet should contain a search box. When "true", the search is only enabled when more facet values are available.

boolean

false

Shadow Parts

Part Description

active-parent

The non-clickable active parent.

all-categories-button

The "View all" button displayed first along the parents.

back-arrow

The back arrow displayed before the clickable parents.

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.

parent-button

The clickable parent button.

parents

The parent values container.

placeholder

The placeholder shown before the first search is executed.

ripple

The ripple effect of the component’s interactive elements.

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-result

The search result value.

search-result-path

The search result path.

search-results

The search results container.

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-count

The facet value count.

value-label

The facet value label.

value-link

The child facet value.

values

The facet values child container.

CSS Custom Content

Name Description

--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.

What's Next for Me?