> ## Documentation Index
> Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Facets

> Interactive filtering component for refining search results by categories and attributes in UI Studio applications

The Facets component in UI Studio provides interactive filters that allow users to refine search results by selecting categories, attributes, and values. Use facets to narrow down large datasets by criteria like manufacturer, category, price range, or any custom field from your data.

## Basic usage

Add a facets component to your UI Studio page to enable filtering capabilities. To build a minimal facets component, you must set a value for the Datastore field and a facet category to display.

<Frame caption="Facets component in the canvas">
  <img src="https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/add-facets.png?fit=max&auto=format&n=qwknCXYlTmFH7Hq2&q=85&s=99c08be5a277270ba2b2e55f5c11ff02" alt="" width="2048" height="1036" data-path="assets/images/lw-platform/ui-studio/add-facets.png" />
</Frame>

If no facets are available for the provided datastore, the component displays an empty state message: "No facets found. Please try adjusting your search criteria."

To add a facet, click the **+** next to the **Facets** selector. Facets display in a vertical list.

## Searchable facet values

Enable search within facet values for categories with many options. When enabled, a search box appears within each facet category, allowing users to quickly find specific values. This is especially useful for facets with many values, for example, cities or product models.

Toggle the **Searchable Facet Values** switch to turn this feature on or off.

## Collapsible facets

Collapsible facets let users show or hide individual facet categories to reduce visual clutter.

<Frame caption="Collapsible facet categories">
  <img src="https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/collapsible-facets.png?fit=max&auto=format&n=qwknCXYlTmFH7Hq2&q=85&s=ee49e5a8e16c4d3b93db2e469895acc8" alt="" width="756" height="386" data-path="assets/images/lw-platform/ui-studio/collapsible-facets.png" />
</Frame>

When enabled, each facet category displays a chevron icon. Users can click to collapse categories they're not using, creating a cleaner interface. The collapsed state persists during the user's session.

Enabling collapsible facets is recommended when you have many facet categories. Users can focus on the filters they're actively using while hiding others.

Toggle the **Collapsible** switch to turn collapsible facet categories on or off.

## Inclusive and exclusive filtering

Enable advanced filtering with inclusion and exclusion operators. These filters let users include or exclude a facet from their search results and create complex filter combinations such as "show products from Sony or Samsung, but not refurbished items."

When enabled, each facet value displays plus and minus icons:

* **+ (Plus)**: Include results that match this facet value.
* **- (Minus)**: Exclude results that match this facet value.

Use inclusive and exclusive filtering for complex filtering through many facets. For simpler interfaces, turn this setting off to avoid overwhelming users with additional controls.

Toggle the **Inclusive/Exclusive** switch to turn this setting on or off.

<Frame caption="Inclusive and exclusive filtering mode">
  <img src="https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/inclusive-exclusive-facets.png?fit=max&auto=format&n=qwknCXYlTmFH7Hq2&q=85&s=2ef343f4a482c001a0ce6665b4742df1" alt="" width="898" height="142" data-path="assets/images/lw-platform/ui-studio/inclusive-exclusive-facets.png" />
</Frame>

## Selected facet pills

Use facet pills to display selected filters as removable pills before the facet categories. These facet pills provide a visual indicator to users about the facets they're actively filtering by.

Users can select individual facet pills to remove that filter from their current search results.

A **Clear All** link also appears, letting users remove all active filters at once.

<Frame caption="Selected facet pills display">
  <img src="https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/selected-facet-pills.png?fit=max&auto=format&n=qwknCXYlTmFH7Hq2&q=85&s=c6410a4246cd1c9f6696d60e4f217409" alt="" width="876" height="276" data-path="assets/images/lw-platform/ui-studio/selected-facet-pills.png" />
</Frame>

Toggle the **Selected Facet Pills** switch to turn this feature on or off.

## Configuration properties

<ParamField path="Datastore" type="dropdown" required>
  Data source that provides facet categories and values. Must be configured in your UI Studio application.
</ParamField>

<ParamField path="Facets Title" type="string" default="">
  Optional text label displayed as the heading above the facets panel.
</ParamField>

<ParamField path="Facets" type="array">
  Configure individual facet fields to display in the component.

  <Expandable title="Properties">
    <ParamField path="Field Name" type="string">
      The field name from your datastore to use as a facet.
    </ParamField>

    <ParamField path="Display Name" type="string">
      The label shown to users for this facet category (for example, "Manufacturer", "Color").
    </ParamField>

    <ParamField path="Multi Select" type="boolean" default="false">
      When enabled, allows users to select multiple values within this facet category.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="Searchable Facet Values" type="boolean" default="false">
  When enabled, adds a search box within each facet category for filtering values. This setting is recommended for facets with ten or more values.
</ParamField>

<ParamField path="Collapsible" type="boolean" default="false">
  When enabled, facet categories can be collapsed and expanded with chevron icons. The collapsed state persists in the user's session.
</ParamField>

<ParamField path="Inclusive/Exclusive" type="boolean" default="false">
  When enabled, displays **+** and **-** icons next to facet values for inclusive or exclusive filtering. This allows complex filter combinations like "include Sony or Samsung, but exclude refurbished".
</ParamField>

<ParamField path="Selected Facet Pills" type="boolean" default="false">
  When enabled, displays active filters as removable pills at the top with a **Clear All** option. Shows inclusive (+) or exclusive (-) indicators when Inclusive/Exclusive mode is enabled.
</ParamField>

<ParamField path="Facets Title Font" type="group">
  Typography settings for the main facets heading or title.

  <Expandable title="Properties">
    <ParamField path="Font Family" type="dropdown" default="Public Sans">
      Font family for facets title.
    </ParamField>

    <ParamField path="Font Weight" type="dropdown" default="Regular">
      Font weight for facets title.

      <Expandable title="Options">
        <ParamField path="Regular" type="option">
          Standard weight.
        </ParamField>

        <ParamField path="Bold" type="option">
          Heavy weight.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="Font Size" type="number" default="14">
      Font size in pixels for facets title.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="Facet Field Font" type="group">
  Typography settings for facet category titles (for example, "Manufacturer", "Color").

  <Expandable title="Properties">
    <ParamField path="Font Family" type="dropdown" default="Public Sans">
      Font family for facet category titles.
    </ParamField>

    <ParamField path="Font Weight" type="dropdown" default="Bold">
      Font weight for facet category titles.

      <Expandable title="Options">
        <ParamField path="Regular" type="option">
          Standard weight.
        </ParamField>

        <ParamField path="Bold" type="option">
          Heavy weight.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="Font Size" type="number" default="14">
      Font size in pixels for facet category titles.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="Facet Value Font" type="group">
  Typography settings for facet values (for example, "Sony", "Purple").

  <Expandable title="Properties">
    <ParamField path="Font Family" type="dropdown" default="Public Sans">
      Font family for facet values.
    </ParamField>

    <ParamField path="Font Weight" type="dropdown" default="Regular">
      Font weight for facet values.

      <Expandable title="Options">
        <ParamField path="Regular" type="option">
          Standard weight.
        </ParamField>

        <ParamField path="Bold" type="option">
          Heavy weight.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="Font Size" type="number" default="14">
      Font size in pixels for facet values.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="Search Input" type="group">
  Typography settings for the search input field within facet categories. Used when **Searchable Facet Values** is enabled.

  <Expandable title="Properties">
    <ParamField path="Font Family" type="dropdown" default="Public Sans">
      Font family for search input text.
    </ParamField>

    <ParamField path="Font Weight" type="dropdown" default="Regular">
      Font weight for search input text.

      <Expandable title="Options">
        <ParamField path="Regular" type="option">
          Standard weight.
        </ParamField>

        <ParamField path="Bold" type="option">
          Heavy weight.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="Font Size" type="number" default="14">
      Font size in pixels for search input text.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="Selected Filters Header" type="group">
  Typography settings for the "Selected Filters:" header text when Selected Facet Pills is enabled.

  <Expandable title="Properties">
    <ParamField path="Font Family" type="dropdown" default="Public Sans">
      Font family for selected filters header.
    </ParamField>

    <ParamField path="Font Weight" type="dropdown" default="Regular">
      Font weight for selected filters header.

      <Expandable title="Options">
        <ParamField path="Regular" type="option">
          Standard weight.
        </ParamField>

        <ParamField path="Bold" type="option">
          Heavy weight.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="Font Size" type="number" default="12">
      Font size in pixels for selected filters header.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="Selected Filter Pill" type="group">
  Typography settings for the filter pill text when Selected Facet Pills is enabled.

  <Expandable title="Properties">
    <ParamField path="Font Family" type="dropdown" default="Public Sans">
      Font family for filter pill text.
    </ParamField>

    <ParamField path="Font Weight" type="dropdown" default="Regular">
      Font weight for filter pill text.

      <Expandable title="Options">
        <ParamField path="Regular" type="option">
          Standard weight.
        </ParamField>

        <ParamField path="Bold" type="option">
          Heavy weight.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="Font Size" type="number" default="14">
      Font size in pixels for filter pill text.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="Colors" type="group">
  Color scheme for the facets component.

  <Expandable title="Properties">
    <ParamField path="Background" type="color" default="#ffffff">
      Background color for the facets container.

      <Color variant="compact">
        <Color.Item name="default" value="#ffffff" />
      </Color>
    </ParamField>

    <ParamField path="Facets Title" type="group">
      Color properties for the facets title.

      <Expandable title="Properties">
        <ParamField path="Facets Title Font" type="color" default="#2C3136">
          Text color for the main facets title.

          <Color variant="compact">
            <Color.Item name="default" value="#2C3136" />
          </Color>
        </ParamField>

        <ParamField path="Facets Title Background" type="color" default="#ffffff">
          Background color for the facets title area.

          <Color variant="compact">
            <Color.Item name="default" value="#ffffff" />
          </Color>
        </ParamField>

        <ParamField path="Facets Title Border" type="color" default="#ffffff">
          Border color for the facets title area.

          <Color variant="compact">
            <Color.Item name="default" value="#ffffff" />
          </Color>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="Facet Field" type="group">
      Color properties for the facet field.

      <Expandable title="Properties">
        <ParamField path="Facet Field Font" type="color" default="#2C3136">
          Text color for facet category titles. Ensure sufficient contrast with background.

          <Color variant="compact">
            <Color.Item name="default" value="#2C3136" />
          </Color>
        </ParamField>

        <ParamField path="Facet Field Background" type="color" default="#ffffff">
          Background color for facet category title rows.

          <Color variant="compact">
            <Color.Item name="default" value="#ffffff" />
          </Color>
        </ParamField>

        <ParamField path="Facet Field Border" type="color" default="#ffffff">
          Border color for facet category title rows.

          <Color variant="compact">
            <Color.Item name="default" value="#ffffff" />
          </Color>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="Facet Value" type="group">
      Color properties for the facet value.

      <Expandable title="Properties">
        <ParamField path="Facet Value Font" type="color" default="#2C3136">
          Text color for facet values. Ensure sufficient contrast with background.

          <Color variant="compact">
            <Color.Item name="default" value="#2C3136" />
          </Color>
        </ParamField>

        <ParamField path="Hover Over" type="color" default="#F9FAFB">
          Background color when hovering over facet values.

          <Color variant="compact">
            <Color.Item name="default" value="#F9FAFB" />
          </Color>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="Facet Search" type="group">
      Color properties for the facet search input.

      <Expandable title="Properties">
        <ParamField path="Facet Search Text" type="color" default="#2C3136">
          Text color for the search input field within facet categories.

          <Color variant="compact">
            <Color.Item name="default" value="#2C3136" />
          </Color>
        </ParamField>

        <ParamField path="Facet Search Background" type="color" default="#ffffff">
          Background color for the search input field within facet categories.

          <Color variant="compact">
            <Color.Item name="default" value="#ffffff" />
          </Color>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="Selected Filters Header" type="group">
      Color properties for the selected filters header.

      <Expandable title="Properties">
        <ParamField path="Title" type="color" default="#2C3136">
          Text color for the "Selected Filters:" header label.

          <Color variant="compact">
            <Color.Item name="default" value="#2C3136" />
          </Color>
        </ParamField>

        <ParamField path="Clear All" type="color" default="#0066cc">
          Text color for the "Clear All" link.

          <Color variant="compact">
            <Color.Item name="default" value="#0066cc" />
          </Color>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="Selected Filter Pill" type="group">
      Color properties for the selected filter pill.

      <Expandable title="Properties">
        <ParamField path="Pill Font" type="color" default="#2C3136">
          Text color for filter pill labels.

          <Color variant="compact">
            <Color.Item name="default" value="#2C3136" />
          </Color>
        </ParamField>

        <ParamField path="Pill Background" type="color" default="#E8E8E8">
          Background color for filter pills.

          <Color variant="compact">
            <Color.Item name="default" value="#E8E8E8" />
          </Color>
        </ParamField>

        <ParamField path="Pill Border" type="color" default="#d0d0d0">
          Border color for filter pills.

          <Color variant="compact">
            <Color.Item name="default" value="#d0d0d0" />
          </Color>
        </ParamField>

        <ParamField path="Pill Icon" type="color" default="#2C3136">
          Color for the remove icon (×) on filter pills.

          <Color variant="compact">
            <Color.Item name="default" value="#2C3136" />
          </Color>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="Inclusive/Exclusive Buttons" type="group">
      Color properties for the inclusive/exclusive buttons.

      <Expandable title="Properties">
        <ParamField path="Background" type="color" default="#ffffff">
          Background color for the + and - buttons when Inclusive/Exclusive mode is enabled.

          <Color variant="compact">
            <Color.Item name="default" value="#ffffff" />
          </Color>
        </ParamField>

        <ParamField path="Border" type="color" default="#ECEEF0">
          Border color for the + and - buttons when Inclusive/Exclusive mode is enabled.

          <Color variant="compact">
            <Color.Item name="default" value="#ECEEF0" />
          </Color>
        </ParamField>

        <ParamField path="Active Background" type="color" default="#2C3136">
          Background color for active + or - buttons when Inclusive/Exclusive mode is enabled.

          <Color variant="compact">
            <Color.Item name="default" value="#2C3136" />
          </Color>
        </ParamField>

        <ParamField path="Active Icon" type="color" default="#ffffff">
          Icon color for active + or - buttons when Inclusive/Exclusive mode is enabled.

          <Color variant="compact">
            <Color.Item name="default" value="#ffffff" />
          </Color>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>