# edit-typeahead

## Overview

The `edit-typeahead` cell type of an `object-table` displays a list of options in a dropdown format. An option can be selected by the user and a consequent action can fire. It includes a search field to allow users to more easily navigate the listed options. `edit-typeahead` is a more advanced version of `edit-select` in that it provides fine grained control over how options are displayed and at what stage they are available.

### Basic Example

{% code title="main.view\.xml" %}

```xml
<object-table ... >
    <column heading="Items">
        <edit-typeahead 
        empty-message="No results found"
        on-search="$:onSearch($object, searchValue)" />
    </column>
</object-table>
```

{% endcode %}

{% code title="main.js" %}

```javascript
function onSearch(object, searchValue) {
    return [
        { label: "Item 1", key: "1" },
        { label: "Item 2", key: "2" },
        { label: "Item 3", key: "3" }
    ];
}
```

{% endcode %}

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-c783e1a3b388e5082c6d015bb27a2931f588d5b4%2Fedit-typeahead-example.png?alt=media)

## Standard Attributes

### `on-search`

**Required**

**Default**: unset

**Triggered when**: The cell is selected or when the user starts to search

**Event parameters**: `$object,` `searchValue`

**Return value**: See more information below.

`on-search` is an event that calls a JS/TS [`$:function`](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml) or [navigation](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/view-navigation). See more details:

{% content-ref url="../../../js-ts-events" %}
[js-ts-events](https://docs.journeyapps.com/reference/build/ui-components/js-ts-events)
{% endcontent-ref %}

{% code title="main.view\.xml" %}

```xml
<object-table ... >
    <column heading="Items">
        <edit-typeahead 
        empty-message="No results found"
        on-search="$:onSearch($object, searchValue)" />
    </column>
</object-table>
```

{% endcode %}

{% code title="main.js" %}

```javascript
function onSearch(object, searchValue) {
    return [
        { label: "Item 1", key: "1" },
        { label: "Item 2", key: "2", icon: 'fa-cube' },
        { label: "Item 3", key: "3", subtext: 'Subtext for item 3' },
        { label: "Item 4", key: "4", subtext: 'Subtext for item 4', icon: 'fa-camera' },
    ];
}
```

{% endcode %}

In this above, `searchValue` will contain `null` when `edit-typeahead` is opened for the first time and will fire again as the user starts typing. If the user clears the text in the search box the `searchValue` will return to `null`.

The `on-search` function should return an array of objects with the following fields:

| Field     | Required? | Description                                                                 |
| --------- | --------- | --------------------------------------------------------------------------- |
| `label`   | Required  | Text that is displayed on each option                                       |
| `key`     | Required  | A unique identifier for each option                                         |
| `icon`    | Optional  | Places an icon on the left of each option                                   |
| `subtext` | Optional  | Subtext that is displayed on each option below the label, in a smaller font |

The `on-search` function can also return sets of grouped items:

{% code title="main.js" %}

```javascript
function onSearch(object, searchValue) {
    return [
        {
            label: 'Group 1',
            items: [
                { label: "Item 1", key: "1" },
                { label: "Item 2", key: "2" },
            ]
        },
        {
            label: 'Group 2',
            items: [
                { label: "Item 3", key: "3" },
                { label: "Item 4", key: "4" },
            ]
        }
    ];
}
```

{% endcode %}

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-a6189a34bf315b26e21dc3e4fda05fa852de1699%2Fedit-typeahead-on-search-grouped.png?alt=media)

The syntax for grouped items includes the following fields:

| Field   | Required? | Description                                                    |
| ------- | --------- | -------------------------------------------------------------- |
| `label` | Required  | The group name that is displayed above the items in the group  |
| `items` | Required  | An array of item objects - see the previous table for details. |

## Advanced Attributes

### `clear-icon`

{% hint style="info" %}
**Version compatibility**

`clear-icon` was introduced in version **4.89.17** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `string`

**Default**: "fa-times"

Specify the icon on the right side of the input that appears when an option was selected. Find a list of available icons [here](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/icons).

### `empty-message`

**Optional**

**Type**: `string` (static text, a [format string](https://docs.journeyapps.com/reference/app-features/xml-format-strings) or the return value of a [JS/TS function](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml))

**Default**: unset

Text that is displayed if no options are available when the user opens the `edit-typeahead` cell or performs a [search](#on-search).

### `show-if` and `hide-if`

{% content-ref url="../../../xml-fields/show-if" %}
[show-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if)
{% endcontent-ref %}

{% content-ref url="../../../xml-fields/hide-if" %}
[hide-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if)
{% endcontent-ref %}