Version: v8 (beta)

ion-action-sheet

An Action Sheet is a dialog that displays 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. Destructive options are made obvious in ios mode. There are multiple ways to dismiss the action sheet, including tapping the backdrop or hitting the escape key on desktop.

Inline Action Sheets (Recommended)

ion-action-sheet 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 Action Sheet.

Using `isOpen`

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

isOpen uses a one-way data binding, meaning it will not automatically be set to false when the Action Sheet is dismissed. Developers should listen for the ionActionSheetDidDismiss or didDismiss event and set isOpen to false. The reason for this is it prevents the internals of ion-action-sheet from being tightly coupled with the state of the application. With a one way data binding, the Action Sheet only needs to concern itself with the boolean value that the reactive variable provides. With a two way data binding, the Action Sheet 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 Action Sheets

The actionSheetController can be used in situations where more control is needed over when the Action Sheet is presented and dismissed.

Buttons

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.

A button can also be passed data via the data property on ActionSheetButton. This will populate the data field in the return value of the onDidDismiss method.

Collecting Role Information on Dismiss

When the didDismiss event is fired, the data and role fields of the event detail can be used to gather information about how the Action Sheet was dismissed.

Console

Console messages will appear here when logged from the example above.

Theming

Action Sheet uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a higher specificity selector.

Styling

We recommend passing a custom class to cssClass in the create method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces.

/* DOES NOT WORK - not specific enough */
.action-sheet-group {
  background: #e5e5e5;
}

/* Works - pass "my-custom-class" in cssClass to increase specificity */
.my-custom-class .action-sheet-group {
  background: #e5e5e5;
}

CSS Custom Properties

Any of the defined CSS Custom Properties can be used to style the Action Sheet without needing to target individual elements.

Accessibility

Screen Readers

Action Sheets set aria properties in order to be accessible to screen readers, but these properties can be overridden if they aren't descriptive enough or don't align with how the action sheet is being used in an app.

Role

Action Sheets are given a role of dialog. In order to align with the ARIA spec, either the aria-label or aria-labelledby attribute must be set.

Action Sheet Description

It is strongly recommended that every Action Sheet have the header property defined, as Ionic will automatically set aria-labelledby to point to the header element. However, if you choose not to include a header, an alternative is to use the htmlAttributes property to provide a descriptive aria-label or set a custom aria-labelledby value.

Angular
Javascript
React
Vue

const actionSheet = await this.actionSheetController.create({
  htmlAttributes: {
    'aria-label': 'action sheet dialog',
  },
});

const actionSheet = await this.actionSheetController.create({
  htmlAttributes: {
    'aria-label': 'action sheet dialog',
  },
});

useIonActionSheet({
  htmlAttributes: {
    'aria-label': 'action sheet dialog',
  },
});

const actionSheet = await actionSheetController.create({
  htmlAttributes: {
    'aria-label': 'action sheet dialog',
  },
});

Action Sheet Buttons Description

Buttons containing text will be read by a screen reader. If a button contains only an icon, or a description other than the existing text is desired, a label should be assigned to the button by passing aria-label to the htmlAttributes property on the button.

Angular
Javascript
React
Vue

const actionSheet = await this.actionSheetController.create({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

const actionSheet = await this.actionSheetController.create({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

useIonActionSheet({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

const actionSheet = await actionSheetController.create({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

Interfaces

ActionSheetButton

interface ActionSheetButton<T = any> {
  text?: string;
  role?: 'cancel' | 'destructive' | 'selected' | string;
  icon?: string;
  cssClass?: string | string[];
  id?: string;
  htmlAttributes?: { [key: string]: any };
  handler?: () => boolean | void | Promise<boolean | void>;
  data?: T;
}

ActionSheetOptions

interface ActionSheetOptions {
  header?: string;
  subHeader?: string;
  cssClass?: string | string[];
  buttons: (ActionSheetButton | string)[];
  backdropDismiss?: boolean;
  translucent?: boolean;
  animated?: boolean;
  mode?: Mode;
  keyboardClose?: boolean;
  id?: string;
  htmlAttributes?: { [key: string]: any };

  enterAnimation?: AnimationBuilder;
  leaveAnimation?: AnimationBuilder;
}

Properties

animated

Description	If `true`, the action sheet will animate.
Attribute	`animated`
Type	`boolean`
Default	`true`

backdropDismiss

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

buttons

Description	An array of buttons for the action sheet.
Attribute	`undefined`
Type	`(string ｜ ActionSheetButton<any>)[]`
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`

enterAnimation

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

Description	Title for the action sheet.
Attribute	`header`
Type	`string ｜ undefined`
Default	`undefined`

htmlAttributes

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

isOpen

Description	If `true`, the action sheet will open. If `false`, the action sheet will close. Use this if you need finer grained control over presentation, otherwise just use the actionSheetController or the `trigger` property. Note: `isOpen` will not automatically be set back to `false` when the action sheet dismisses. You will need to do that in your code.
Attribute	`is-open`
Type	`boolean`
Default	`false`

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 action sheet 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`

subHeader

Description	Subtitle for the action sheet.
Attribute	`sub-header`
Type	`string ｜ undefined`
Default	`undefined`

translucent

Description	If `true`, the action sheet will be translucent. Only applies when the mode is `"ios"` and the device supports `backdrop-filter`.
Attribute	`translucent`
Type	`boolean`
Default	`false`

trigger

Description	An ID corresponding to the trigger element that causes the action sheet to open when clicked.
Attribute	`trigger`
Type	`string ｜ undefined`
Default	`undefined`

Events

Name	Description
`didDismiss`	Emitted after the action sheet has dismissed. Shorthand for ionActionSheetDidDismiss.
`didPresent`	Emitted after the action sheet has presented. Shorthand for ionActionSheetWillDismiss.
`ionActionSheetDidDismiss`	Emitted after the action sheet has dismissed.
`ionActionSheetDidPresent`	Emitted after the action sheet has presented.
`ionActionSheetWillDismiss`	Emitted before the action sheet has dismissed.
`ionActionSheetWillPresent`	Emitted before the action sheet has presented.
`willDismiss`	Emitted before the action sheet has dismissed. Shorthand for ionActionSheetWillDismiss.
`willPresent`	Emitted before the action sheet has presented. Shorthand for ionActionSheetWillPresent.

Methods

dismiss

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

onDidDismiss

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

onWillDismiss

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

present

Description	Present the action sheet 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 action sheet group
`--button-background`	Background of the action sheet button
`--button-background-activated`	Background of the action sheet button when pressed. Note: setting this will interfere with the Material Design ripple.
`--button-background-activated-opacity`	Opacity of the action sheet button background when pressed
`--button-background-focused`	Background of the action sheet button when tabbed to
`--button-background-focused-opacity`	Opacity of the action sheet button background when tabbed to
`--button-background-hover`	Background of the action sheet button on hover
`--button-background-hover-opacity`	Opacity of the action sheet button background on hover
`--button-background-selected`	Background of the selected action sheet button
`--button-background-selected-opacity`	Opacity of the selected action sheet button background
`--button-color`	Color of the action sheet button
`--button-color-activated`	Color of the action sheet button when pressed
`--button-color-focused`	Color of the action sheet button when tabbed to
`--button-color-hover`	Color of the action sheet button on hover
`--button-color-selected`	Color of the selected action sheet button
`--color`	Color of the action sheet text
`--height`	height of the action sheet
`--max-height`	Maximum height of the action sheet
`--max-width`	Maximum width of the action sheet
`--min-height`	Minimum height of the action sheet
`--min-width`	Minimum width of the action sheet
`--width`	Width of the action sheet

Slots

No slots available for this component.

Inline Action Sheets (Recommended)​

Using isOpen​

Controller Action Sheets​

Buttons​

Collecting Role Information on Dismiss​

Theming​

Styling​

CSS Custom Properties​

Accessibility​

Screen Readers​

Role​

Action Sheet Description​

Action Sheet Buttons Description​

Interfaces​

ActionSheetButton​

ActionSheetOptions​

Properties​

animated​

backdropDismiss​

buttons​

cssClass​

enterAnimation​

header​

htmlAttributes​

isOpen​

keyboardClose​

leaveAnimation​

mode​

subHeader​

translucent​

trigger​

Events​

Methods​

dismiss​

onDidDismiss​

onWillDismiss​

present​

CSS Shadow Parts​

CSS Custom Properties​

Slots​

Contents

Inline Action Sheets (Recommended)

Using `isOpen`

Controller Action Sheets

Buttons

Collecting Role Information on Dismiss

Theming

Styling

CSS Custom Properties

Accessibility

Screen Readers

Role

Action Sheet Description

Action Sheet Buttons Description

Interfaces

ActionSheetButton

ActionSheetOptions

Properties

animated

backdropDismiss

buttons

cssClass

enterAnimation

header

htmlAttributes

isOpen

keyboardClose

leaveAnimation

mode

subHeader

translucent

trigger

Events

Methods

dismiss

onDidDismiss

onWillDismiss

present

CSS Shadow Parts

CSS Custom Properties

Slots