@capawesome/capacitor-option-picker

v0.1.1

Published

a month ago

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

0High
0Medium
0Low

capacitor plugin native ionic android ios capacitor-plugin option picker list picker native picker select dropdown single choice uipickerview

Capacitor Option Picker Plugin

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

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 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 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 |

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

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:

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.

Demo

| iOS | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | |

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:

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:

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

present(...)

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 | PresentOptions |

Returns: Promise<PresentResult>

Since: 0.1.0

Interfaces

PresentResult

| Prop | Type | Description | Since | | ----------- | ------------------- | --------------------------------- | ----- | | value | string | The value of the selected option. | 0.1.0 |

PresentOptions

| Prop | Type | Description | Default | Since | | ---------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----- | | cancelButtonText | string | The text of the cancel button. | 'Cancel' | 0.1.0 | | doneButtonText | string | The text of the done button. | 'Ok' | 0.1.0 | | options | PickerOption[] | The options the user can choose from. Must contain at least one option. | | 0.1.0 | | theme | 'auto' | 'light' | 'dark' | The theme of the picker. auto follows the system appearance. | 'auto' | 0.1.0 | | title | string | The title of the picker. | | 0.1.0 | | value | string | 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 | string | The text displayed for the option. | 0.1.0 | | value | string | The value returned when the option is selected. | 0.1.0 |

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 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 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: Show native action sheets.
Datetime Picker: Let the user pick a date and time with a native picker.
Dialog: Display native alert, confirm, and prompt dialogs.

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.