Need help upgrading to Ionic Framework 4.0? Get assistance with our Enterprise Migration Services EXPLORE NOW

ActionSheetController

Improve this doc

An Action Sheet is a dialog that lets the user choose from a set of options. It appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. Dangerous (destructive) options are made obvious in ios mode. There are easy ways to cancel out of the action sheet, such as tapping the backdrop or hitting the escape key on desktop.

An action sheet is created from an array of buttons, with each button including properties for its text, and optionally a handler and role. If a handler returns false then the action sheet will not be dismissed. An action sheet can also optionally have a title, subTitle and an icon.

A button's role property can either be destructive or cancel. Buttons without a role property will have the default look for the platform. Buttons with the cancel role will always load as the bottom button, no matter where they are in the array. All other buttons will be displayed in the order they have been added to the buttons array. Note: We recommend that destructive buttons are always the first button in the array, making them the top button. Additionally, if the action sheet is dismissed by tapping the backdrop, then it will fire the handler from the button with the cancel role.

You can pass all of the action sheet's options in the first argument of the create method: ActionSheet.create(opts). Otherwise the action sheet's instance has methods to add options, like setTitle() or addButton().

Usage

import { ActionSheetController } from 'ionic-angular'

export class MyClass{

 constructor(public actionSheetCtrl: ActionSheetController) { }

 presentActionSheet() {
   const actionSheet = this.actionSheetCtrl.create({
     title: 'Modify your album',
     buttons: [
       {
         text: 'Destructive',
         role: 'destructive',
         handler: () => {
           console.log('Destructive clicked');
         }
       },
       {
         text: 'Archive',
         handler: () => {
           console.log('Archive clicked');
         }
       },
       {
         text: 'Cancel',
         role: 'cancel',
         handler: () => {
           console.log('Cancel clicked');
         }
       }
     ]
   });

   actionSheet.present();
 }
}

Instance Members

config

create(opts)

Open an action sheet with a title, subTitle, and an array of buttons

Param Type Details
opts ActionSheetOptions

Action sheet options

Advanced

ActionSheet create options

Option Type Description
title string The title for the Action Sheet.
subTitle string The sub-title for the Action Sheet.
cssClass string Additional classes for custom styles, separated by spaces.
enableBackdropDismiss boolean If the Action Sheet should close when the user taps the backdrop.
buttons array<any> An array of buttons to display.

ActionSheet button options

Option Type Description
text string The buttons text.
icon icon The buttons icons.
handler any An express the button should evaluate.
cssClass string Additional classes for custom styles, separated by spaces.
role string How the button should be displayed, destructive or cancel. If no role is provided, it will display the button without any additional styles.

Dismissing And Async Navigation

After an action sheet has been dismissed, the app may need to also transition to another page depending on the handler's logic. However, because multiple transitions were fired at roughly the same time, it's difficult for the nav controller to cleanly animate multiple transitions that may have been kicked off asynchronously. This is further described in the Nav Transition Promises section. For action sheets, this means it's best to wait for the action sheet to finish its transition out before starting a new transition on the same nav controller.

In the example below, after the button has been clicked, its handler waits on async operation to complete, then it uses pop to navigate back a page in the same stack. The potential problem is that the async operation may have been completed before the action sheet has even finished its transition out. In this case, it's best to ensure the action sheet has finished its transition out first, then start the next transition.

const actionSheet = this.actionSheetCtrl.create({
  title: 'Hello',
  buttons: [{
    text: 'Ok',
    handler: () => {
      // user has clicked the action sheet button
      // begin the action sheet's dimiss transition
      let navTransition = actionSheet.dismiss();

      // start some async method
      someAsyncOperation().then(() => {
        // once the async operation has completed
        // then run the next nav transition after the
        // first transition has finished animating out

        navTransition.then(() => {
          this.nav.pop();
        });
      });
      return false;
    }
  }]
});

actionSheet.present();

It's important to note that the handler returns false. A feature of button handlers is that they automatically dismiss the action sheet when their button was clicked, however, we'll need more control regarding the transition. Because the handler returns false, then the action sheet does not automatically dismiss itself. Instead, you now have complete control of when the action sheet has finished transitioning, and the ability to wait for the action sheet to finish transitioning out before starting a new transition.

Sass Variables

Property Default Description
$action-sheet-width 100%

Width of the action sheet

$action-sheet-max-width 500px

Maximum width of the action sheet

Property Default Description
$action-sheet-ios-text-align center

Text align of the action sheet

$action-sheet-ios-padding-top 0

Padding top of the action sheet

$action-sheet-ios-padding-end 10px

Padding end of the action sheet

$action-sheet-ios-padding-bottom $action-sheet-ios-padding-top

Padding bottom of the action sheet

$action-sheet-ios-padding-start $action-sheet-ios-padding-end

Padding start of the action sheet

$action-sheet-ios-group-margin-top 10px

Top margin of the action sheet button group

$action-sheet-ios-group-margin-bottom 10px

Bottom margin of the action sheet button group

$action-sheet-ios-background #f9f9f9

Background color of the action sheet

$action-sheet-ios-border-color #d6d6da

Border color of the action sheet

$action-sheet-ios-border-radius 13px

Border radius of the action sheet

$action-sheet-ios-title-padding 1.5rem

Padding of the action sheet title

$action-sheet-ios-title-color #8f8f8f

Color of the action sheet title

$action-sheet-ios-title-font-size 1.3rem

Font size of the action sheet title

$action-sheet-ios-title-font-weight 400

Font weight of the action sheet title

$action-sheet-ios-title-border-radius 0

Border radius of the action sheet title

$action-sheet-ios-button-min-height 5.6rem

Minimum height of the action sheet button

$action-sheet-ios-button-padding 18px

Padding of the action sheet button

$action-sheet-ios-button-text-color #007aff

Text color of the action sheet button

$action-sheet-ios-button-font-size 2rem

Font size of the action sheet button

$action-sheet-ios-button-border-width $hairlines-width

Border width of the action sheet button

$action-sheet-ios-button-border-style solid

Border style of the action sheet button

$action-sheet-ios-button-border-color #d1d3d6

Border color of the action sheet button

$action-sheet-ios-button-background transparent

Background color of the action sheet button

$action-sheet-ios-button-background-activated #ebebeb

Background color of the activated action sheet button

$action-sheet-ios-button-destructive-text-color #f53d3d

Destructive text color of the action sheet button

$action-sheet-ios-button-cancel-background #fff

Background color of the action sheet cancel button

$action-sheet-ios-button-cancel-font-weight 600

Font weight of the action sheet cancel button

Property Default Description
$action-sheet-md-text-align start

Text align of the action sheet

$action-sheet-md-background #fafafa

Background color of the action sheet

$action-sheet-md-padding-top .8rem

Padding top of the action sheet

$action-sheet-md-padding-bottom .8rem

Padding bottom of the action sheet

$action-sheet-md-title-color #757575

Color of the action sheet title

$action-sheet-md-title-font-size 1.6rem

Font size of the action sheet title

$action-sheet-md-title-padding-top 11px

Padding top of the action sheet title

$action-sheet-md-title-padding-end 16px

Padding end of the action sheet title

$action-sheet-md-title-padding-bottom 17px

Padding bottom of the action sheet title

$action-sheet-md-title-padding-start $action-sheet-md-title-padding-end

Padding start of the action sheet title

$action-sheet-md-button-min-height 4.8rem

Minimum height of the action sheet button

$action-sheet-md-button-text-color #222

Text color of the action sheet button

$action-sheet-md-button-font-size 1.6rem

Font size of the action sheet button

$action-sheet-md-button-padding-top 0

Padding top of the action sheet button

$action-sheet-md-button-padding-end 16px

Padding end of the action sheet button

$action-sheet-md-button-padding-bottom $action-sheet-md-button-padding-top

Padding bottom of the action sheet button

$action-sheet-md-button-padding-start $action-sheet-md-button-padding-end

Padding start of the action sheet button

$action-sheet-md-button-background transparent

Background color of the action sheet button

$action-sheet-md-button-background-activated #f1f1f1

Background color of the action sheet activated button

$action-sheet-md-icon-font-size 2.4rem

Font size of the icon in the action sheet button

$action-sheet-md-icon-width 2.3rem

Width of the icon in the action sheet button

$action-sheet-md-icon-text-align center

Text align of the icon in the action sheet button

$action-sheet-md-icon-vertical-align middle

Vertical align of the icon in the action sheet button

$action-sheet-md-icon-margin-top 0

Margin top of the icon in the action sheet button

$action-sheet-md-icon-margin-end 32px

Margin end of the icon in the action sheet button

$action-sheet-md-icon-margin-bottom 0

Margin bottom of the icon in the action sheet button

$action-sheet-md-icon-margin-start 0

Margin start of the icon in the action sheet button

Property Default Description
$action-sheet-wp-text-align start

Text align of the action sheet

$action-sheet-wp-background #fff

Background color of the action sheet

$action-sheet-wp-padding-top .8rem

Padding top of the action sheet

$action-sheet-wp-padding-bottom .8rem

Padding bottom of the action sheet

$action-sheet-wp-box-shadow-color rgba(0, 0, 0, .2)

Box shadow color of the action sheet

$action-sheet-wp-box-shadow 0 -1px 0 $action-sheet-wp-box-shadow-color

Box shadow of the action sheet

$action-sheet-wp-title-padding-top 11px

Padding top of the action sheet title

$action-sheet-wp-title-padding-end 16px

Padding end of the action sheet title

$action-sheet-wp-title-padding-bottom 17px

Padding bottom of the action sheet title

$action-sheet-wp-title-padding-start $action-sheet-wp-title-padding-end

Padding start of the action sheet title

$action-sheet-wp-title-font-size 2rem

Font size of the action sheet title

$action-sheet-wp-title-color #4d4d4d

Color of the action sheet title

$action-sheet-wp-title-text-align $action-sheet-wp-text-align

Text align of the action sheet title

$action-sheet-wp-button-height 4.8rem

Height of the action sheet button

$action-sheet-wp-button-text-color #4d4d4d

Text color of the action sheet button

$action-sheet-wp-button-font-size 1.5rem

Font size of the action sheet button

$action-sheet-wp-button-padding-top 0

Padding top of the action sheet button

$action-sheet-wp-button-padding-end 16px

Padding end of the action sheet button

$action-sheet-wp-button-padding-bottom $action-sheet-wp-button-padding-top

Padding bottom of the action sheet button

$action-sheet-wp-button-padding-start $action-sheet-wp-button-padding-end

Padding start of the action sheet button

$action-sheet-wp-button-text-align $action-sheet-wp-text-align

Text align of the action sheet button

$action-sheet-wp-button-background transparent

Background color of the action sheet button

$action-sheet-wp-button-background-activated $list-wp-activated-background-color

Background color of the action sheet activated button

$action-sheet-wp-icon-font-size 2.4rem

Font size of the icon in the action sheet button

$action-sheet-wp-icon-width 2.3rem

Width of the icon in the action sheet button

$action-sheet-wp-icon-text-align center

Text align of the icon in the action sheet button

$action-sheet-wp-icon-vertical-align middle

Vertical align of the icon in the action sheet button

$action-sheet-wp-icon-margin-top 0

Margin top of the icon in the action sheet button

$action-sheet-wp-icon-margin-end 20px

Margin end of the icon in the action sheet button

$action-sheet-wp-icon-margin-bottom 0

Margin bottom of the icon in the action sheet button

$action-sheet-wp-icon-margin-start 0

Margin start of the icon in the action sheet button

Related

ActionSheet Component Docs

API

Native

General