> For the complete documentation index, see [llms.txt](https://ordino-ai.gitbook.io/ordino-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ordino-ai.gitbook.io/ordino-ai/sdk-reference/components/dropdown.md).

# DropDown

### Usage : `dropdown`

### 🧩 Code

The Dropdown class is designed to interact with common drop-down element

To insert a code block with syntax highlighting:

{% tabs %}
{% tab title="Cypress" %}

```javascript
import { oi } from "@ordino.ai/spartify-engine";

oi.ui.dropdown(this.ddl_element).click()
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
import { oi } from "@ordino.ai/spartify-engine";

await oi.ui(this.page).dropdown(this.ddl_element).click()
```

{% endtab %}
{% endtabs %}

### Methods

**openDropdown(): void**\
Opens the dropdown.

* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>oi.ui.dropdown(this.element).openDropdown()
</strong></code></pre>

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).openDropdown()
```

{% endtab %}
{% endtabs %}

**closeDropdown(): void**\
Closes the dropdown..

* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).closeDropdown()
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).closeDropdown()
```

{% endtab %}
{% endtabs %}

**selectByIndex(index: number, forceSelect:boolean): void**\
Selects an option by its index.

* **@param** `{index}` – The index of the option to select.
* **@param** `{force}` – true (optional)
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).selectByIndex(1,true)
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).selectByIndex(1,true)
```

{% endtab %}
{% endtabs %}

**selectByText(text: string, forceSelect:boolean): void**\
Selects an option by its text.

* **@param** `{index}` – The index of the option to select.
* **@param** `{force}` – true (optional)
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).selectByText('text',true)
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).selectByText('text',true)
```

{% endtab %}
{% endtabs %}

**selectByValue(value: string , forceSelect:boolean): void**\
Selects an option by its value.

* **@param** `{value}` – The value of the option to select.
* **@param** `{force}` – true (optional)
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).selectByValue('text',true)
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).selectByValue('text',true)
```

{% endtab %}
{% endtabs %}

**filterByText(text: string , forceSelect:boolean): void**\
Filters options by text.

* **@param** `{text}` – The text to filter options by.
* **@param** `{force}` – true (optional)
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).filterByText('text')
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).filterByText('text')
```

{% endtab %}
{% endtabs %}

**filterByValue(value: string): void**\
Filters options by value.

* **@param** `{value}` – The value to filter options by
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).filterByValue('test')
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).filterByValue('text')
```

{% endtab %}
{% endtabs %}

**filterByPartialText(partialText: string): void**\
Filters options by partial text.

* **@param** `{text}` – The partial text to filter options by.
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).filterByPartialText('test')
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).filterByPartialText('test')
```

{% endtab %}
{% endtabs %}

**clearSelection(): void**\
Clears the current selection in the dropdown.

* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).clearSelection()
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).clearSelection()
```

{% endtab %}
{% endtabs %}

**selectRandomOption(): void**\
Selects a random option from the dropdown.

* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).selectRandomOption()
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
oi.ui.dropdown(this.element).selectRandomOption()
```

{% endtab %}
{% endtabs %}

**clickOptionByText(text: string, forceSelect:boolean): void**\
Clicks an option by its text.

* **@param** `{text}` – The text to filter options by.
* **@param** `{force}` – true (optional)
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).clickOptionByText('text',true)
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).clickOptionByText('text',true)
```

{% endtab %}
{% endtabs %}

### Assertions <a href="#assertions" id="assertions"></a>

**assertSelectedText(text: string): void**\
Clicks an option by its text.

* **@param** `{text}` – The partial text to filter options by.
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).assertSelectedText('text')
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).assertSelectedText('text')
```

{% endtab %}
{% endtabs %}

**assertSelectedValue(value: string): void**\
The value to assert against the selected option’s value.

* **@param** `{value}` – The  value to filter options by.
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).assertSelectedValue('text')
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).assertSelectedValue('text')
```

{% endtab %}
{% endtabs %}

**assertContainsOption(value: string): void**\
Asserts that the dropdown contains an option with the given value.

* **@param** `{option}` – The value of the option to check for
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).assertContainsOption('text')
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).assertContainsOption('text')
```

{% endtab %}
{% endtabs %}

**assertNotContainsOption(value: string): void**\
Asserts that the dropdown does not contain an option with the given value.

* **@param** `{text}` – The partial text to filter options by.
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).filterByPartialText('test')
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).filterByPartialText('test')
```

{% endtab %}
{% endtabs %}

**assertNotContainsOption(value: string): void**\
Asserts that the dropdown does not contain an option with the given value.

* **@param** `{text}` – The value of the option to check for.
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).assertNotContainsOption('text')
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).assertNotContainsOption('text')
```

{% endtab %}
{% endtabs %}

**assertIsDisabled(): void**\
Asserts that the dropdown is disabled.

* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).assertIsDisabled()
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).assertIsDisabled()
```

{% endtab %}
{% endtabs %}

**assertIsEnabled(): void**\
Asserts that the dropdown is enabled.

* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).assertIsEnabled()
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).assertIsEnabled()
```

{% endtab %}
{% endtabs %}

**assertOptionCount(count: number): void**\
Asserts that the number of options in the dropdown matches the given count

* **@param** `{count}` – The expected number of options.
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).assertOptionCount(3)
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).assertOptionCount(3)
```

{% endtab %}
{% endtabs %}

**assertSelectedByIndex(index: number): void**\
Asserts that the selected option’s index matches the given index.

* **@param** `{index}` – The index to assert against the selected option’s index.
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).assertSelectedByIndex(1)
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).assertSelectedByIndex(1)
```

{% endtab %}
{% endtabs %}

**assertIsVisible(): void**\
Asserts that the dropdown is visible.

* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).assertIsVisible()
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).assertIsVisible()
```

{% endtab %}
{% endtabs %}

**assertPlaceholder(text: string): void**\
Asserts that the placeholder text matches the given text.

* **@param** `{text}` – The placeholder to assert
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).assertPlaceholder('text')
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).assertPlaceholder('text')
```

{% endtab %}
{% endtabs %}

### Scrolling <a href="#scrolling" id="scrolling"></a>

**scrollToOption(value: string): void;**\
Scrolls to an option with the given value.

* **@param** `{value}` – The value of the option to scroll to.
* **@returns** `void`

{% tabs %}
{% tab title="Cypress" %}

```javascript
oi.ui.dropdown(this.element).scrollToOption('text')
```

{% endtab %}

{% tab title="Playwright" %}

```javascript
await oi.ui(this.page).dropdown(this.element).scrollToOption('text')
```

{% endtab %}
{% endtabs %}

### Custom Events <a href="#scrolling-actions" id="scrolling-actions"></a>

Ordino allows you to build **custom actions** or **user journeys** by directly interacting with the underlying tool’s native methods and actions.

This approach gives you full control, bypassing Ordino’s abstraction layer, and ensures you can leverage **tool-specific capabilities** as needed.

* `locator` → The element locator (e.g., XPath, CSS selector, or tool-specific reference).
* Returns → A tool element object on which you can invoke native actions (e.g., `.click()`, `.type()`).

```javascript
// Generic pattern
element(locator): object
```

### <sub>Ordino Custom Mode</sub>

Using Ordino’s direct tool method reference:

```javascript
// Ordino direct-to-tool approach
oi.ui.element('@xpath').click()
```

Here, Ordino will call the Cypress (or other tool) element object directly, rather than going through Ordino’s wrapper.

\
Building User Journeys

By chaining multiple `oi.ui.element()` calls, you can construct full user journeys while still working with **native tool methods**.

#### Example: Login Flow

```javascript
// Enter username
oi.ui.element('//input[@id="username"]').type('testuser')

// Enter password
oi.ui.element('//input[@id="password"]').type('secret')

// Click login button
oi.ui.element('(//*[contains(text(),"Login")])[1]').click()
```

***

### Key Notes

* Use this mode when you need **maximum control** over the test framework.
* This does not abstract or transform the call – it **executes directly on the tool object** (e.g., Cypress, Playwright, etc.).
* Perfect for **custom journeys, advanced locators, or tool-specific actions** not exposed by Ordino’s higher-level API.


---

# 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 dynamically by asking a question.

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

```
GET https://ordino-ai.gitbook.io/ordino-ai/sdk-reference/components/dropdown.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.