---
title: Capacitor Option Picker Plugin
description: Capacitor plugin that lets the user pick an option from a list using a native picker. A wheel picker on iOS and a Material 3 dialog on Android.
tags:
  - Android
  - iOS
search:
  boost: 2
faq: true
status: new
github_repo: capawesome-team/capacitor-plugins
npm_package: "@capawesome/capacitor-option-picker"
---

# Capacitor Option Picker Plugin

Capacitor plugin that lets the user pick an option from a list using a native picker.

<div class="capawesome-z29o10a">
  <a href="https://capawesome.io/" target="_blank">
    <img alt="Ship a fix in one command with Capawesome Cloud Live Updates, no store review" src="https://capawesome.io/assets/banners/cloud-ship-a-fix-in-one-command.png" />
  </a>
</div>

## Features

- 📋 **Native Picker**: Present the platform's native single-choice picker: a wheel picker on iOS and a Material 3 dialog on Android.
- ✅ **Preselection**: Open the picker with the current value already selected.
- 📝 **Title & Buttons**: Customize the title and the texts of the done and cancel buttons.
- 📚 **Long Lists**: Scroll smoothly through long lists of options on both platforms.
- 🎨 **Themed**: Follows the system appearance or a forced light or dark theme, and adopts your app's Material theme on Android.
- 🔒 **App Store safe**: Uses only official platform APIs.
- 🤝 **Compatibility**: Works alongside the [Datetime Picker](https://capawesome.io/docs/sdks/capacitor/datetime-picker/) plugin.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Option Picker plugin is typically used as a native replacement for HTML `<select>` elements, for example:

- **Form inputs**: Let the user pick a country, language, or category in a form.
- **Settings screens**: Let the user choose a value such as a unit, a theme, or a refresh interval.
- **Filters and sorting**: Let the user pick a sort order or a filter category in a list view.
- **Guided flows**: Ask the user to pick a value before continuing to the next step.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Demo

| iOS                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://raw.githubusercontent.com/capawesome-team/capacitor-plugins/main/packages/option-picker/assets/option-picker-demo-ios.png" width="266" alt="iOS Demo" /> |

## Installation

You can use our **AI-Assisted Setup** to install the plugin.
Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-option-picker` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```bash
npm install @capawesome/capacitor-option-picker
npx cap sync
```

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$androidxMaterialVersion` version of `com.google.android.material:material` (default: `1.12.0`)

### iOS

No additional configuration is required for this plugin.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to present a native option picker and read the selected value.

### Present a picker

Present a native picker with a title and a list of options. Use the `value` option to preselect the current value. The result contains the value of the selected option. Only available on Android and iOS:

```typescript
import { OptionPicker } from '@capawesome/capacitor-option-picker';

const presentPicker = async () => {
  const { value } = await OptionPicker.present({
    title: 'Select a country',
    options: [
      { label: 'Germany', value: 'de' },
      { label: 'France', value: 'fr' },
      { label: 'Spain', value: 'es' },
    ],
    value: 'fr',
  });
  console.log('Selected value:', value);
};
```

### Handle cancellation

If the user cancels or dismisses the picker, the returned promise is rejected with the `ErrorCode.Canceled` error code:

```typescript
import { ErrorCode, OptionPicker } from '@capawesome/capacitor-option-picker';

const presentPicker = async () => {
  try {
    const { value } = await OptionPicker.present({
      options: [
        { label: 'Small', value: 's' },
        { label: 'Medium', value: 'm' },
        { label: 'Large', value: 'l' },
      ],
    });
    console.log('Selected value:', value);
  } catch (error) {
    if (error.code === ErrorCode.Canceled) {
      console.log('The user canceled the picker.');
    }
  }
};
```

## API

<docgen-index>

* [`present(...)`](#present)
* [Interfaces](#interfaces)

</docgen-index>

<docgen-api>
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->

### present(...)

```typescript
present(options: PresentOptions) => Promise<PresentResult>
```

Present a native picker that lets the user select one option from a list.

The returned promise is rejected with the `ErrorCode.Canceled` error code
if the user cancels or dismisses the picker.

Only available on Android and iOS.

| Param         | Type                                                      |
| ------------- | --------------------------------------------------------- |
| **`options`** | <code><a href="#presentoptions">PresentOptions</a></code> |

**Returns:** <code>Promise&lt;<a href="#presentresult">PresentResult</a>&gt;</code>

**Since:** 0.1.0

--------------------


### Interfaces


#### PresentResult

| Prop        | Type                | Description                       | Since |
| ----------- | ------------------- | --------------------------------- | ----- |
| **`value`** | <code>string</code> | The value of the selected option. | 0.1.0 |


#### PresentOptions

| Prop                   | Type                                     | Description                                                                                                                | Default               | Since |
| ---------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----- |
| **`cancelButtonText`** | <code>string</code>                      | The text of the cancel button.                                                                                             | <code>'Cancel'</code> | 0.1.0 |
| **`doneButtonText`**   | <code>string</code>                      | The text of the done button.                                                                                               | <code>'Ok'</code>     | 0.1.0 |
| **`options`**          | <code>PickerOption[]</code>              | The options the user can choose from. Must contain at least one option.                                                    |                       | 0.1.0 |
| **`theme`**            | <code>'auto' \| 'light' \| 'dark'</code> | The theme of the picker. `auto` follows the system appearance.                                                             | <code>'auto'</code>   | 0.1.0 |
| **`title`**            | <code>string</code>                      | The title of the picker.                                                                                                   |                       | 0.1.0 |
| **`value`**            | <code>string</code>                      | The value of the option that is selected when the picker opens. If no option has this value, the first option is selected. |                       | 0.1.0 |


#### PickerOption

| Prop        | Type                | Description                                     | Since |
| ----------- | ------------------- | ----------------------------------------------- | ----- |
| **`label`** | <code>string</code> | The text displayed for the option.              | 0.1.0 |
| **`value`** | <code>string</code> | The value returned when the option is selected. | 0.1.0 |

</docgen-api>

## FAQ

### How is this plugin different from other similar plugins?

It presents the platform's own single-choice picker on Android and iOS through a fully typed API: a wheel picker with a toolbar on iOS and a Material 3 dialog on Android, the same controls the operating systems use for `<select>` elements. The current value can be preselected, the title and button texts are customizable, and cancellation is reported with a dedicated error code, all using only official platform APIs. Actively maintained against the latest Capacitor version, it lets a single dependency replace non-native dropdown components.

### Which native UI is used on each platform?

On iOS, the plugin presents a `UIPickerView` in a bottom sheet with a toolbar that contains the cancel button, the title, and the done button. On iOS 26 and later, the bottom sheet uses the system's Liquid Glass design. On Android, the plugin presents a Material 3 dialog with a scrollable single-choice list and a done and cancel button. Both follow the system appearance, including dark mode.

### Does the Android dialog use my app's theme?

Yes, if your app uses a Material Components or Material 3 theme, the dialog inherits its colors and shapes. If your app uses an AppCompat theme (the Capacitor default), the dialog uses a Material 3 theme with the system's dynamic colors on Android 12 and later, and the Material 3 baseline colors on older versions. To use your own brand colors in that case, switch your app theme to a Material 3 theme such as `Theme.Material3.DayNight.NoActionBar`.

### Can I force a light or dark theme?

Yes, set the `theme` option to `light` or `dark`. By default (`auto`), the picker follows the system appearance.

### What happens when the user cancels the picker?

The returned promise is rejected with the `ErrorCode.Canceled` error code. This happens when the user taps the cancel button, taps outside of the picker, swipes the picker down on iOS 26 and later, or presses the back button on Android. See the [Handle cancellation](#handle-cancellation) example.

### Which option is selected when the picker opens?

The option whose value matches the `value` option is selected. If no `value` is provided or no option matches, the first option is selected.

### When should I use the Option Picker instead of the Action Sheet plugin?

Use the Option Picker when the user has to choose a value, for example in a form or a settings screen. It is designed for long lists and highlights the current value. Use the [Action Sheet](https://capawesome.io/docs/sdks/capacitor/action-sheet/) plugin when the user has to choose between a few actions to perform.

### Does this plugin work on the Web?

No, the `present(...)` method is only available on Android and iOS. On the Web, use a regular HTML `<select>` element instead.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Action Sheet](https://capawesome.io/docs/sdks/capacitor/action-sheet/): Show native action sheets.
- [Datetime Picker](https://capawesome.io/docs/sdks/capacitor/datetime-picker/): Let the user pick a date and time with a native picker.
- [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/): Display native alert, confirm, and prompt dialogs.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/option-picker/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/option-picker/LICENSE).