> For the complete documentation index, see [llms.txt](https://docs.fact-finder.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fact-finder.com/webcomponents-overview/api/navigation/sortbox.md).

# Sortbox

\`ff-sortbox\` and \`ff-sortbox-select\` let users change result ordering. They use FactFinder sort options and support native or custom dropdown templates.

## Documentation

With the sort box element you can change the order in which products are displayed. There are two kinds of sort boxes:

* `ff-sortbox-select` is a native HTML `select` element.
* `ff-sortbox` is a custom-built dropdown element.

Both can be used with or without customization.

Sort box elements are populated with the `sortItems` portion from the FactFinder search response. Inside the HTML template of the sort box item, you therefore have access to all those data fields (*DescribedSortItem*).

### Native HTML select (`ff-sortbox-select`)

The `ff-sortbox-select` element displays a native HTML `select` element.

{% tabs %}
{% tab title="Minimal setup" %}

```html
<ff-sortbox-select></ff-sortbox-select>
```

{% endtab %}

{% tab title="Custom option template" %}

```html
<ff-sortbox-select>
    <option>{{description}}</option>
</ff-sortbox-select>
```

{% endtab %}

{% tab title="Custom select and option templates" %}

```html
<ff-sortbox-select>
    <select class="example-class">
        <option>Sort by: {{description}}</option>
    </select>
</ff-sortbox-select>
```

{% endtab %}
{% endtabs %}

#### Rendered HTML

When set up like in the last example above, the rendered HTML could look like this.

```html
<ff-sortbox-select>
    <select class="example-class">
        <option>Sort by: Title A-Z</option>
        <option>Sort by: Title Z-A</option>
        <option>Sort by: Relevance</option>
    </select>
</ff-sortbox-select>
```

### Custom-built dropdown (`ff-sortbox`)

The `ff-sortbox` element is a custom-built dropdown. If you do not define any `ff-sortbox-item` templates, items will default to `<ff-sortbox-item>{{description}}</ff-sortbox-item>`.

```html
<ff-sortbox></ff-sortbox>

<!-- Equivalent to: -->
<ff-sortbox>
    <ff-sortbox-item>{{description}}</ff-sortbox-item>
</ff-sortbox>
```

If you do specify `ff-sortbox-item` templates, you may define an individual template for each item in the `sortItems` list of the FactFinder response.

FactFinder provides each item with a `name` and an `order` field. When you combine them, you get a unique identifier that you can use in the `key` attribute of the `ff-sortbox-item` template.

You do not have to specify templates for all sort item types. Only define those that you wish to deviate from the default.

Available keys are as follows:

| Key                                    | Description                                                                                        |
| -------------------------------------- | -------------------------------------------------------------------------------------------------- |
| default.template                       | This is the fallback template for all options that have no other template defined.                 |
| Relevancy.desc                         | FactFinder always returns an option to sort by relevance.                                          |
| *{name from FactFinder response}*.asc  | An option as specified in FactFinder in **ascending** order. (e.g. `Price.asc`, `Title.asc`)       |
| *{name from FactFinder response}*.desc | An option as specified in FactFinder in **descending** order. (e.g. `Discount.desc`, `Title.desc`) |

Inside the `ff-sortbox-item`, you can access the sort option name with `{{description}}`.

```html
<ff-sortbox>
    <!--
    "default.template" is a pseudo key used to specify a default template for all sort box items.
    -->
    <ff-sortbox-item key="default.template" class="customCssClass">
        <span>Default Style: {{description}}</span>
    </ff-sortbox-item>

    <!-- Override relevance layout. -->
    <ff-sortbox-item key="Relevancy.desc">Relevance</ff-sortbox-item>

    <!--
    Other keys depend on your data returned by FactFinder. Their format is always "FIELDNAME.ORDER".
    -->
    <ff-sortbox-item key="Price.asc">
        <span style="font-size: 18px">Overridden for: {{description}}</span>
    </ff-sortbox-item>

    <ff-sortbox-item key="Rating.desc">
        <span><em>Overridden for: {{description}}</em></span>
    </ff-sortbox-item>

    <!-- If the body is empty, the item's `description` will be filled in automatically.  -->
    <ff-sortbox-item key="Discount.desc"></ff-sortbox-item>
    <!-- Equivalent to: -->
    <ff-sortbox-item key="Discount.desc">{{description}}</ff-sortbox-item>

</ff-sortbox>
```

#### show-selected / show-selected-first

By default, the selected sort option will disappear from the dropdown list and appear in the static container of the element. Setting the `show-selected` attribute means the selected option remains part of the available options in the dropdown list.

When `show-selected` is set, you can additionally set `show-selected-first` to make the selected option appear as the first item in the dropdown. Without `show-selected`, the setting of `show-selected-first` has no effect.

#### collapse-onblur

When the element loses focus, the dropdown will collapse. To make it remain expanded, set the `collapse-onblur="false"` attribute.

```html
<ff-sortbox collapse-onblur="false"></ff-sortbox>
```

#### Rendered HTML

When set up like in the example above, the rendered HTML could look like this.

```html
<ff-sortbox collapse-onblur="false" tabindex="1" opened>
    <div class="ffw-selected-container">
        <ff-sortbox-item key="Relevancy.desc" class="ffw-selected" style="display: block;">Relevance</ff-sortbox-item>
    </div>

    <div class="ffw-dropdown-container" style="overflow: hidden; height: auto;" opened>
        <ff-sortbox-item key="Price.asc" style="display: block;">Lowest price</ff-sortbox-item>

        <ff-sortbox-item key="Price.desc" style="display: block;">Highest price</ff-sortbox-item>

        <ff-sortbox-item key="Discount_Percent.asc" style="display: block;">Discount asc</ff-sortbox-item>

        <ff-sortbox-item key="Discount_Percent.desc" style="display: block;">Discount desc</ff-sortbox-item>
    </div>
</ff-sortbox>
```

## Demo

{% embed url="<https://search-web-components.fact-finder.de/demos/5.x/ff-sortbox>" %}

## API

### `ff-sortbox-select`

#### Properties

| Name              | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| **items** (Array) | The data from FactFinder. Set this through JavaScript only. |

#### Events

| Name            | Description                                                                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **dom-updated** | This event is triggered when the element has received new data and the template for this element and all sub elements have been punched out. |

### `ff-sortbox`

#### Properties

| Name                                                                        | Description                                                                                     |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **items** (Array)                                                           | The data from FactFinder. Set this through JavaScript only.                                     |
| **opened** (Boolean)                                                        | Determines if the sort box is opened.                                                           |
| **show-selected** (Boolean)                                                 | Determines if the selected sort option also appears in the dropdown.                            |
| **show-selected-first** (Boolean)                                           | Determines if the selected sort option appears first in the dropdown. Requires `show-selected`. |
| **collapse-onblur** (String) **Options**: "true", "false" (default: "true") | Determines if the dropdown closes automatically after losing focus.                             |

#### Methods

| Name                         | Description                                              |
| ---------------------------- | -------------------------------------------------------- |
| **toggle(expand?: Boolean)** | Opens or closes the element, based on its current state. |
| **expand()**                 | Expands the dropdown element.                            |
| **collapse()**               | Collapses the dropdown element.                          |

#### Events

| Name            | Description                                                                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **dom-updated** | This event is triggered when the element has received new data and the template for this element and all sub elements have been punched out. |

### `ff-sortbox-item`

#### Properties

| Name                  | Description                                                                                                       |
| --------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **sortItem** (Object) | The data from FactFinder. Available through JavaScript only.                                                      |
| **key** (String)      | Defines the FactFinder sort-item template. Use `{sort item 'name'}.{sort item 'order'}`, for example `Price.asc`. |

#### Events

| Name            | Description                                                                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **dom-updated** | This event is triggered when the element has received new data and the template for this element and all sub elements have been punched out. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.fact-finder.com/webcomponents-overview/api/navigation/sortbox.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.