atomic-category-facet

This is for:

Developer

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 multi-value field whose values are formatted hierarchically. 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.

    This component uses ; to separate individual values, and the character that’s defined with the delimiting-character attribute to separate hierarchical levels within each value. We recommend setting this attribute to | instead of using the default, which is ;. The following is an example of the recommended hierarchical formatting:

    clothing; clothing|sale; clothing|sale|shoes; clothing|sale|shoes|kids; clothing|sale|shoes|kids|sneakers;

  • 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

On an ecommerce 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.

References

Categories, Facets—and Browsable Facets?

Don’t Lose Face with Facets

Properties

Property Attribute Description Type Default

basePath

base-path

The base path shared by all values for the facet.

Specify the property as an array using a JSON string representation:

 <atomic-category-facet base-path='["first value", "second value"]' ></atomic-category-facet>

string | string[]

'[]'

delimitingCharacter

delimiting-character

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

Note: If you use the example formatting for the associated multi-value field, you must set this value to | or the facet won’t display properly.

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

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

sortCriteria

sort-criteria

The sort criterion to apply to the returned facet values. Possible values are 'alphanumeric' and 'occurrences'. For this criterion to apply to the top-layer facet values, disable facet value ordering in your Dynamic Navigation Experience configuration.

"alphanumeric" | "occurrences"

'occurrences'

tabsExcluded

tabs-excluded

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

Set this property as a stringified JSON array, for example:

 <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 shouldn’t be used at the same time as tabs-excluded.

Set this property as a stringified JSON array, for example:

 <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

false

Shadow Parts

Part Description

active-parent

The clickable active parent displayed first within the last sub-parents.

all-categories-button

The "View all" button displayed first within 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.

leaf-value

A facet value with no child value.

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.

node-value

A facet value with child values.

parent-button

The clickable parent button displayed first within sub-parents.

parents

The container surrounding the whole hierarchy of values.

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

The search result value.

search-result-path

The search result path.

search-results

The search results container.

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.

sub-parents

The container surrounding a sub-hierarchy of values.

value-count

The facet value count within a value button.

value-label

The facet value label within a value button.

value-link

The clickable value displayed first within values.

values

The container surrounding either the children of the active value or the values at the base.

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.