Skip to main content
Version: v7 (beta)

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.

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;
/**
* The optional text to assign as the aria-label on the picker column option.
*/
ariaLabel?: string;
}

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

Properties

animated

DescriptionIf true, the picker will animate.
Attributeanimated
Typeboolean
Defaulttrue

backdropDismiss

DescriptionIf true, the picker will be dismissed when the backdrop is clicked.
Attributebackdrop-dismiss
Typeboolean
Defaulttrue

buttons

DescriptionArray of buttons to be displayed at the top of the picker.
Attributeundefined
TypePickerButton[]
Default[]

columns

DescriptionArray of columns to be displayed in the picker.
Attributeundefined
TypePickerColumn[]
Default[]

cssClass

DescriptionAdditional classes to apply for custom CSS. If multiple classes are provided they should be separated by spaces.
Attributecss-class
Typestring ๏ฝœ string[] ๏ฝœ undefined
Defaultundefined

duration

DescriptionNumber of milliseconds to wait before dismissing the picker.
Attributeduration
Typenumber
Default0

enterAnimation

DescriptionAnimation to use when the picker is presented.
Attributeundefined
Type((baseEl: any, opts?: any) => Animation) ๏ฝœ undefined
Defaultundefined

htmlAttributes

DescriptionAdditional attributes to pass to the picker.
Attributeundefined
Typeundefined ๏ฝœ { [key: string]: any; }
Defaultundefined

isOpen

DescriptionIf true, the picker will open. If false, the picker will close. Use this if you need finer grained control over presentation, otherwise just use the pickerController or the trigger property. Note: isOpen will not automatically be set back to false when the picker dismisses. You will need to do that in your code.
Attributeis-open
Typeboolean
Defaultfalse

keyboardClose

DescriptionIf true, the keyboard will be automatically dismissed when the overlay is presented.
Attributekeyboard-close
Typeboolean
Defaulttrue

leaveAnimation

DescriptionAnimation to use when the picker is dismissed.
Attributeundefined
Type((baseEl: any, opts?: any) => Animation) ๏ฝœ undefined
Defaultundefined

mode

DescriptionThe mode determines which platform styles to use.
Attributemode
Type"ios" ๏ฝœ "md"
Defaultundefined

showBackdrop

DescriptionIf true, a backdrop will be displayed behind the picker.
Attributeshow-backdrop
Typeboolean
Defaulttrue

trigger

DescriptionAn ID corresponding to the trigger element that causes the picker to open when clicked.
Attributetrigger
Typestring ๏ฝœ undefined
Defaultundefined

Events

NameDescription
didDismissEmitted after the picker has dismissed. Shorthand for ionPickerDidDismiss.
didPresentEmitted after the picker has presented. Shorthand for ionPickerWillDismiss.
ionPickerDidDismissEmitted after the picker has dismissed.
ionPickerDidPresentEmitted after the picker has presented.
ionPickerWillDismissEmitted before the picker has dismissed.
ionPickerWillPresentEmitted before the picker has presented.
willDismissEmitted before the picker has dismissed. Shorthand for ionPickerWillDismiss.
willPresentEmitted before the picker has presented. Shorthand for ionPickerWillPresent.

Methods

dismiss

DescriptionDismiss the picker overlay after it has been presented.
Signaturedismiss(data?: any, role?: string) => Promise<boolean>

getColumn

DescriptionGet the column that matches the specified name.
SignaturegetColumn(name: string) => Promise<PickerColumn ๏ฝœ undefined>

onDidDismiss

DescriptionReturns a promise that resolves when the picker did dismiss.
SignatureonDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss

DescriptionReturns a promise that resolves when the picker will dismiss.
SignatureonWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>

present

DescriptionPresent the picker overlay after it has been created.
Signaturepresent() => Promise<void>

CSS Shadow Parts

No CSS shadow parts available for this component.

CSS Custom Properties

NameDescription
--backdrop-opacityOpacity of the backdrop
--backgroundBackground of the picker
--background-rgbBackground of the picker in rgb format
--border-colorBorder color of the picker
--border-radiusBorder radius of the picker
--border-styleBorder style of the picker
--border-widthBorder width of the picker
--heightHeight of the picker
--max-heightMaximum height of the picker
--max-widthMaximum width of the picker
--min-heightMinimum height of the picker
--min-widthMinimum width of the picker
--widthWidth of the picker

Slots

No slots available for this component.