ion-picker

scoped

A Picker is a dialog that displays a row of buttons and columns underneath. It appears on top of the app's content, and at the bottom of the viewport.

Inline Pickers (Recommended)

ion-picker can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the Picker.

Using isOpen

The isOpen property on ion-picker allows developers to control the presentation state of the Picker from their application state. This means when isOpen is set to true the Picker will be presented, and when isOpen is set to false the Picker will be dismissed.

isOpen uses a one-way data binding, meaning it will not automatically be set to false when the Picker is dismissed. Developers should listen for the ionPickerDidDismiss or didDismiss event and set isOpen to false. The reason for this is it prevents the internals of ion-picker from being tightly coupled with the state of the application. With a one way data binding, the Picker only needs to concern itself with the boolean value that the reactive variable provides. With a two way data binding, the Picker needs to concern itself with both the boolean value as well as the existence of the reactive variable itself. This can lead to non-deterministic behaviors and make applications harder to debug.

Controller Pickers

The pickerController can be used in situations where more control is needed over when the Picker is presented and dismissed.

Multiple Columns

The columns property can be used to display a Picker with multiple columns of different options.

Interfaces

PickerButton

interface PickerButton {
  text?: string;
  role?: string;
  cssClass?: string | string[];
  handler?: (value: any) => boolean | void;
}

PickerColumn

interface PickerColumn {
  name: string;
  align?: string;
  selectedIndex?: number;
  prevSelected?: number;
  prefix?: string;
  suffix?: string;
  options: PickerColumnOption[];
  cssClass?: string | string[];
  columnWidth?: string;
  prefixWidth?: string;
  suffixWidth?: string;
  optionsWidth?: string;
}

PickerColumnOption

interface PickerColumnOption {
  text?: string;
  value?: any;
  disabled?: boolean;
  duration?: number;
  transform?: string;
  selected?: boolean;
}

PickerOptions

interface PickerOptions {
  columns: PickerColumn[];
  buttons?: PickerButton[];
  cssClass?: string | string[];
  showBackdrop?: boolean;
  backdropDismiss?: boolean;
  animated?: boolean;

  mode?: Mode;
  keyboardClose?: boolean;
  id?: string;
  htmlAttributes?: { [key: string]: any };

  enterAnimation?: AnimationBuilder;
  leaveAnimation?: AnimationBuilder;
}

Usage

Angular

<ion-button expand="block" (click)="presentPicker()">Show Picker</ion-button>

import { Component } from '@angular/core';
import { PickerController } from '@ionic/angular';
@Component({
  selector: 'app-picker-example',
  template: 'picker-example.component.html'
})
export class PickerExample {
  private selectedAnimal: string;
  constructor(private pickerController: PickerController) { }
  
  async presentPicker() {
    const picker = await this.pickerController.create({
      buttons: [
        {
          text: 'Confirm',
          handler: (selected) => {
            this.selectedAnimal = selected.animal.value;
          },
        }
      ],
      columns: [
        {
          name: 'animal',
          options: [
            { text: 'Dog', value: 'dog' },
            { text: 'Cat', value: 'cat' },
            { text: 'Bird', value: 'bird' },
          ]
        }
      ]
    });
    await picker.present();
  }
}

React

/* Using with useIonPicker Hook */

import React, { useState } from 'react';
import { IonButton, IonContent, IonPage, useIonPicker } from '@ionic/react';

const PickerExample: React.FC = () => {
  const [present] = useIonPicker();
  const [value, setValue] = useState('');
  return (
    <IonPage>
      <IonContent>
        <IonButton
          expand="block"
          onClick={() =>
            present({
              buttons: [
                {
                  text: 'Confirm',
                  handler: (selected) => {
                    setValue(selected.animal.value)
                  },
                },
              ],
              columns: [
                {
                  name: 'animal',
                  options: [
                    { text: 'Dog', value: 'dog' },
                    { text: 'Cat', value: 'cat' },
                    { text: 'Bird', value: 'bird' },
                  ],
                },
              ],
            })
          }
        >
          Show Picker
        </IonButton>
        <IonButton
          expand="block"
          onClick={() =>
            present(
              [
                {
                  name: 'animal',
                  options: [
                    { text: 'Dog', value: 'dog' },
                    { text: 'Cat', value: 'cat' },
                    { text: 'Bird', value: 'bird' },
                  ],
                },
                {
                  name: 'vehicle',
                  options: [
                    { text: 'Car', value: 'car' },
                    { text: 'Truck', value: 'truck' },
                    { text: 'Bike', value: 'bike' },
                  ],
                },
              ],
              [
                {
                  text: 'Confirm',
                  handler: (selected) => {
                    setValue(`${selected.animal.value}, ${selected.vehicle.value}`)
                  },
                },
              ]
            )
          }
        >
          Show Picker using params
        </IonButton>
        {value && (
          <div>Selected Value: {value}</div>
        )}
      </IonContent>
    </IonPage>
  );
};

Vue

<template>
  <div>
    <ion-button @click="openPicker">SHOW PICKER</ion-button>
    <p v-if="picked.animal">picked: {{ picked.animal.text }}</p>
  </div>
</template>

<script>
import { IonButton, pickerController } from "@ionic/vue";
export default {
  components: {
    IonButton,
  },
  data() {
    return {
      pickingOptions: {
        name: "animal",
        options: [
          { text: "Dog", value: "dog" },
          { text: "Cat", value: "cat" },
          { text: "Bird", value: "bird" },
        ],
      },
      picked: {
        animal: "",
      },
    };
  },
  methods: {
    async openPicker() {
      const picker = await pickerController.create({
        columns: [this.pickingOptions],
        buttons: [
          {
            text: "Cancel",
            role: "cancel",
          },
          {
            text: "Confirm",
            handler: (value) => {
              this.picked = value;
              console.log(`Got Value ${value}`);
            },
          },
        ],
      });
      await picker.present();
    },
  },
};
</script>

Properties

animated

Description	If true, the picker will animate.
Attribute	animated
Type	boolean
Default	true

backdropDismiss

Description	If true, the picker will be dismissed when the backdrop is clicked.
Attribute	backdrop-dismiss
Type	boolean
Default	true

buttons

Description	Array of buttons to be displayed at the top of the picker.
Attribute	undefined
Type	PickerButton[]
Default	[]

columns

Description	Array of columns to be displayed in the picker.
Attribute	undefined
Type	PickerColumn[]
Default	[]

cssClass

Description	Additional classes to apply for custom CSS. If multiple classes are provided they should be separated by spaces.
Attribute	css-class
Type	string ｜ string[] ｜ undefined
Default	undefined

duration

Description	Number of milliseconds to wait before dismissing the picker.
Attribute	duration
Type	number
Default	0

enterAnimation

Description	Animation to use when the picker is presented.
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

htmlAttributes

Description	Additional attributes to pass to the picker.
Attribute	undefined
Type	undefined ｜ { [key: string]: any; }
Default	undefined

keyboardClose

Description	If true, the keyboard will be automatically dismissed when the overlay is presented.
Attribute	keyboard-close
Type	boolean
Default	true

leaveAnimation

Description	Animation to use when the picker is dismissed.
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

mode

Description	The mode determines which platform styles to use.
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

showBackdrop

Description	If true, a backdrop will be displayed behind the picker.
Attribute	show-backdrop
Type	boolean
Default	true

Events

Name	Description
ionPickerDidDismiss	Emitted after the picker has dismissed.
ionPickerDidPresent	Emitted after the picker has presented.
ionPickerWillDismiss	Emitted before the picker has dismissed.
ionPickerWillPresent	Emitted before the picker has presented.

Methods

dismiss

Description	Dismiss the picker overlay after it has been presented.
Signature	dismiss(data?: any, role?: string) => Promise<boolean>

getColumn

Description	Get the column that matches the specified name.
Signature	getColumn(name: string) => Promise<PickerColumn ｜ undefined>

onDidDismiss

Description	Returns a promise that resolves when the picker did dismiss.
Signature	onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss

Description	Returns a promise that resolves when the picker will dismiss.
Signature	onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>

present

Description	Present the picker overlay after it has been created.
Signature	present() => Promise<void>

CSS Shadow Parts

No CSS shadow parts available for this component.

CSS Custom Properties

Name	Description
--backdrop-opacity	Opacity of the backdrop
--background	Background of the picker
--background-rgb	Background of the picker in rgb format
--border-color	Border color of the picker
--border-radius	Border radius of the picker
--border-style	Border style of the picker
--border-width	Border width of the picker
--height	Height of the picker
--max-height	Maximum height of the picker
--max-width	Maximum width of the picker
--min-height	Minimum height of the picker
--min-width	Minimum width of the picker
--width	Width of the picker

Slots

No slots available for this component.