> 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/web-components-4.x./api/navigation/sortbox.md).

# Sortbox

Let shoppers sort products with native or custom dropdowns.

## Documentation

### Overview

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:

<details>

<summary>Available keys</summary>

| Key                                    | Description                                                                                        |
| -------------------------------------- | -------------------------------------------------------------------------------------------------- |
| default.template                       | This is the fallback template for all options that have no other template defined.                 |
| ff.relevance                           | 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`) |

</details>

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="ff.relevance">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**

Set `collapse-onblur="true"` to collapse the dropdown when the element loses focus. It defaults to `false`.

```html
<ff-sortbox collapse-onblur="true"></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" show-selected="true" show-selected-first="false" tabindex="1" opened>
    <div class="ffw-selected-container">
        <ff-sortbox-item key="Rating.desc" class="ffw-selected">
            <span><em>Overridden for: Rating descending</em></span>
        </ff-sortbox-item>
    </div>

    <div class="ffw-dropdown-container">
        <ff-sortbox-item key="ff.relevance">Relevance</ff-sortbox-item>
        <ff-sortbox-item key="Price.asc">
            <span style="font-size: 18px">Overridden for: Price ascending</span>
        </ff-sortbox-item>
        <ff-sortbox-item key="Price.desc" class="customCssClass">
            <span>Default Style: Price descending</span>
        </ff-sortbox-item>
        <ff-sortbox-item key="Rating.asc" class="customCssClass">
            <span>Default Style: Rating ascending</span>
        </ff-sortbox-item>
        <ff-sortbox-item key="Rating.desc" class="ffw-showSelected">
            <span><em>Overridden for: Rating descending</em></span>
        </ff-sortbox-item>
    </div>
</ff-sortbox>
```

### Example

Use a fixed static label by hiding the selected container. Add a click handler that toggles the sortbox.

```html
<div style="display: inline-block">
    <div class="sortBoxCaption" onclick="toggleSortbox('#sortbox1');">
        Sort items..
    </div>
    <ff-sortbox id="sortbox1" show-selected="true" show-selected-first="true"></ff-sortbox>
</div>

<script>
    function toggleSortbox(selector) {
        document.querySelector(selector).toggle();
    }
</script>

<style>
    .sortBoxCaption {
        margin: 0;
        padding: 10px;
        cursor: pointer;
        border: 1px solid black;
        display: inline-block;
        font-weight: bold;
    }

    #sortbox1 {
        border: none;
        display: block;
        margin-top: -1px;
        margin-left: 1px;
    }

    #sortbox1 ff-sortbox-item.ffw-showSelected {
        background-color: lightgray;
    }

    #sortbox1 .ffw-selected-container {
        display: none !important;
    }
</style>
```

## Demo

Try the [Sortbox demo](https://search-web-components.fact-finder.de/demos/4.x/ff-sortbox).

## API code

### `ff-sortbox`

**Properties**

<details>

<summary>Properties</summary>

| Name                                                                         | Description                                                               |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **items** (Array) (default: empty)                                           | Data from FactFinder. Set this through JavaScript only.                   |
| **opened** (Boolean) Options: true, false (default: false)                   | Determines whether the sort box is open.                                  |
| **show-selected** (String) Options: "true", "false" (default: "false")       | Shows the selected sort option in the dropdown.                           |
| **show-selected-first** (String) Options: "true", "false" (default: "false") | Displays the selected sort option first. Requires `show-selected="true"`. |
| **collapse-onblur** (String) Options: "true", "false" (default: "false")     | Closes the dropdown when it loses focus.                                  |

</details>

**Methods**

<details>

<summary>Methods</summary>

| Name                           | Description                  |
| ------------------------------ | ---------------------------- |
| **toggle(collapse?: Boolean)** | Opens or closes the element. |
| **show()**                     | Opens the dropdown.          |
| **hide()**                     | Closes the dropdown.         |

</details>

**Events**

<details>

<summary>Events</summary>

| Name            | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| **dom-updated** | Fires after the element receives data and renders its templates. |

</details>

### `ff-sortbox-item`

**Properties**

<details>

<summary>Properties</summary>

| Name                                    | Description           |
| --------------------------------------- | --------------------- |
| **sort-item** (Object) (default: empty) | Data from FactFinder. |

</details>

**Events**

<details>

<summary>Events</summary>

| Name            | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| **dom-updated** | Fires after the element receives data and renders its templates. |

</details>


---

# 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/web-components-4.x./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.