ion-picker
Contents
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.
Single Column
Display a list of options in a single, scrollable column.
Multiple Columns
Display 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;
refresh?: () => void;
}
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
- React
- Vue
<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();
}
}
/* 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>
);
};
<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 ๏ฝ undefined) => 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 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 |