# object-dropdown

## Overview

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

* `object-dropdown` is supported in all versions of the JourneyApps Container and Runtime.
* It received several functional updates in version **4.84.0** of the JourneyApps Runtime, including the ability to [bind](#bind) to an array, which allows a user to select multiple options.
  {% endhint %}

The `object-dropdown` UI component lists objects from a [database query](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects) or [array](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects#arrays) for selection by the user. Once an object, or multiple objects (since runtime version 4.84.0) are selected, they can be stored as a field, or used to further your app's workflow.

### Basic Example

#### Binding a single object

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

```xml
<var name="countries" type="query:country" />
<!-- OR -->
<var name="countries" type="array:country" />

<var name="selected_country" type="country" />

<object-dropdown label="Country of residence" query="countries" bind="selected_country" required="false" />
```

{% endcode %}

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

```javascript
function init() {
     view.countries = DB.country.all();
     // OR
     view.countries = DB.country.all().toArray();
}
```

{% endcode %}

#### Binding multiple objects

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

```xml
<var name="countries" type="query:country" />
<!-- OR -->
<var name="countries" type="array:country" />

<var name="selected_countries" type="array:country" />

<object-dropdown label="Country of residence" query="countries" bind="selected_countries" required="false" />
```

{% endcode %}

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

```javascript
function init() {
     view.countries = DB.country.all();
     // OR
     view.countries = DB.country.all().toArray();
}
```

{% endcode %}

A selected option in the `object-dropdown` component:

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

List of options in the `object-dropdown` component:

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

{% hint style="info" %}
**Note**

By default, when 12 or more options are listed in an `object-dropdown` a search box appears at the top of the list of options. It can be used to more efficiently find an option. See the [search-controls reference](#search-controls) for more information.
{% endhint %}

## Standard Attributes

### `bind`

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

**Example - bind to a single object:**

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

```xml
 <var name="countries" type="query:country" />
 <var name="selected_country" type="country" />

 <object-dropdown label="Country of residence" placeholder="Select a country" query="countries" bind="selected_country" required="false" />
```

{% endcode %}

<figure><img src="https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FHquo2L5dZpn6ZUfeK83y%2FScreen%20Shot%202022-09-01%20at%203.14.55%20PM.png?alt=media&#x26;token=51b86d4f-2a8b-4b17-8746-f8aae049ee27" alt=""><figcaption></figcaption></figure>

#### Example - bind to an array:

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

Binding an `object-dropdown` to an array was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

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

```xml
<var name="countries" type="query:country" />
<var name="selected_countries" type="array:country" />

<object-dropdown label="Previous countries of residence" placeholder="Select all that apply" query="countries" bind="selected_countries" required="false" />
```

{% endcode %}

<figure><img src="https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FqUVBk4w4jLhtgJirusx0%2FScreen%20Shot%202022-09-01%20at%203.17.40%20PM.png?alt=media&#x26;token=b952a8fd-fc45-4a88-8459-af7bfbacc6a0" alt=""><figcaption></figcaption></figure>

### `label`

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

### `query`

**Required**

**Default**: unset

`query` contains the name of the [database query](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects) or [array](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects#arrays) variable to populate the objects in the `object-dropdown`.

```xml
<var name="countries" type="query:country" />
<!-- OR -->
<var name="countries" type="array:country" />

<object-dropdown query="countries" bind="selected_country" required="false" />
```

### `required`

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

## Advanced Attributes

### `align-content` <a href="#standard-attributes" id="standard-attributes"></a>

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

`align-content` was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

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

### `align-dialog-content`

**Optional**

**Type**: `center` | `left` | `right`

**Default**: `center`

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

`align-dialog-content` was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

Specifies how the content of the list of options dialog should be aligned. This includes the display value of each option, as well as the header text of the dialog.

```xml
<object-dropdown label="Country of residence" align-dialog-content="left" query="countries" bind="selected_country" />
```

### `align-label`

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

### `clear-button-visibility`

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

### `dialog-title`

**Optional**

**Type**: `string`

**Default**: "Choose an option"

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

`dialog-title` was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

Header text of the dialog that displays the list of options of the `object-dropdown`.

```xml
<object-dropdown label="Country of residence" dialog-title="Choose the country of residence" query="countries" bind="selected_country" />
```

### `disabled`

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

### `display`

**Optional**

**Type**: `string`

**Default**: The `<display/>` tag of the object as defined in the app's data model

Specifies the display value of each option in the `object-dropdown` list. Can be a static string, a [format string](https://docs.journeyapps.com/reference/app-features/xml-format-strings) or a [JS/TS function](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml).

{% code title="schema.xml" %}

```xml
<model name="country" label="Country">
    <field name="name" label="Name" type="text:name"/>
    <field name="population" label="Population" type="integer"/>
    
    <display>{name}</display>
</model>
```

{% endcode %}

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

```xml
<!-- Here the display value for each option is the country's name and population, separated by a "-" -->
<object-dropdown label="Country of residence" display="{name} - {population}" query="countries" bind="selected_country" required="true" />
```

{% endcode %}

### `empty-message`

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

`empty-message` was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

**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 to list once the user opens the `object-dropdown`.

### `icon-position` <a href="#standard-attributes" id="standard-attributes"></a>

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

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

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

### `id`

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

### `label-case`

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

`label-case` was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

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

### `label-color`

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

### `modifier-text`

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

`modifier-text` was introduced in version **4.84.0** of the JourneyApps Run
{% endhint %}

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

### `on-change`

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

### `placeholder`

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

### `search-controls`

**Optional**

**Type**: `auto` | `none` | `show`

**Default**: `auto`

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

`search-controls` was introduced in version **4.84.0** of the JourneyApps Runtime`.`
{% endhint %}

Set the visibility of the search box of the `object-dropdown` component. `auto` shows the search box when the list of options contains 12 options or more. `none` never shows the search box, and `show` always shows the search box at the top of the list of options.

```xml
<object-dropdown label="Country of residence" query="countries" bind="selected_country" search-controls="show" />
```

### `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 %}

## Component Methods

The following component methods are available when an [`id`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id) is assigned to the component and `component.objectDropdown({id:'my-id'})` is called from JS/TS:

### `clear`

Programmatically clear the selected value(s) bound to the `object-dropdown`.

### `clearSearch`

Programmatically clear a value entered into the search box.

### `openDropdown`

Programmatically open the list of items.

### `closeDropdown`

Programmatically close the list of items.

### `scrollDown`

Programmatically scroll down the list of items when the `object-dropdown` is opened.

### `scrollIntoView`

Programmatically scroll until the `object-dropdown` is visible in the view.

### `scrollUp`

Programmatically scroll up the list of items when the `object-dropdown` is opened.

### `selectItem`

Programmatically select an item from the list by its display value.

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

```xml
<var name="countries" type="query:country" />
<var name="selected_country" type="country" />

<object-dropdown id="my-dropdown" query="countries" bind="selected_country" label="Country" />
```

{% endcode %}

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

```javascript
function select() {
    component.objectDropdown({id: 'my-dropdown'}).openDropdown(); // Need to open the dropdown first
    component.objectDropdown({id: 'my-dropdown'}).selectItem("Germany");
}
```

{% endcode %}

### `selectItemByIndex`

Programmatically select an item from the list by its index. **Note**: Indexes begin at 1.

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

```xml
<var name="countries" type="query:country" />
<var name="selected_country" type="country" />

<object-dropdown id="my-dropdown" query="countries" bind="selected_country" label="Country" />
```

{% endcode %}

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

```javascript
function select() {
    component.objectDropdown({id: 'my-dropdown'}).openDropdown(); // Need to open the dropdown first
    component.objectDropdown({id: 'my-dropdown'}).selectItemByIndex(2);
    // Selects the second country in the list
}
```

{% endcode %}

### `setSearch`

Programmatically enter a search value and triggers a search of the `object-dropdown`.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-dropdown.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.