ons-action-sheet

Action/bottom sheet that is displayed on top of current screen. This element can either be attached directly to the <body> or dynamically created from a template using the ons.createElement(template, { append: true }) utility function and the <template> tag. The action sheet is useful for displaying a list of options and asking the user to make a decision. A ons-action-sheet-button is provided for this purpose, although it can contain any type of content. It will automatically be displayed as Material Design (bottom sheet) when running on an Android device.

Tutorial

Action sheets

Onsen UI provides <ons-action-sheet> and <ons-action-sheet-button> elements. Use them to create a dialog that slides from the bottom of the screen to give user options.

<ons-action-sheet id="sheet" cancelable title="From template">
  <ons-action-sheet-button icon="md-square-o">Label</ons-action-sheet-button>
  <ons-action-sheet-button icon="md-square-o">Label</ons-action-sheet-button>
  <ons-action-sheet-button icon="md-close">Cancel</ons-action-sheet-button>
</ons-action-sheet>

This component is referred as “Bottom sheets” in the Material Design spec.

You can display or cancel the action sheet by calling its methods show or hide respectively.

Dynamic action sheet

You can also create and open an action sheet dynamically with the method ons.openActionSheet.

This method takes as argument an object where you can define the action sheet’s properties (e.g. id, title) and the buttons inside it.

ons.openActionSheet({
  title: 'My Action Sheet',
  cancelable: true,
  buttons: ['Label 0', 'Label 1', 'Label 2']
});

See also

Attributes

Attributes are added directly to the element. You can do this in HTML or JS.

HTML: <ons-action-sheet someAttribute="true" anotherAttribute><ons-action-sheet>
JS: document.querySelector('ons-action-sheet').setAttribute('someAttribute', 'true')

Name Type Description
title String Optional title of the action sheet. A new element will be created containing this string. Optional.
modifier String The appearance of the action sheet. Optional.
cancelable If this attribute is set the action sheet can be closed by tapping the background or by pressing the back button on Android devices. Optional.
disabled If this attribute is set the action sheet is disabled. Optional.
animation String
default
The animation used when showing and hiding the action sheet. Can be either "none" or "default". Optional.
animation-options Expression Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'}. Optional.
mask-color String
rgba(0, 0, 0, 0.2)
Color of the background mask. Default is "rgba(0, 0, 0, 0.2)". Optional.

Properties

Properties are accessed on the element through JS, and should be get and set directly. For example: document.querySelector('ons-action-sheet').onDeviceBackButton.

Name Description
onDeviceBackButton Back-button handler.
visible Whether the action sheet is visible or not.
disabled Whether the action sheet is disabled or not.
cancelable Whether the action sheet is cancelable or not. A cancelable action sheet can be closed by tapping the background or by pressing the back button on Android devices.

Preset Modifiers

Modifiers are set in the modifier attribute. To use more than one, separate them by spaces. For example:
<ons-action-sheet modifier="material modifier2"><ons-action-sheet>.

Name Description
material Display a Material Design bottom sheet.

Methods

These methods are called directly on the DOM element. Get a reference to the element in JS, and the methods below will be available to call on it. For example: document.querySelector('ons-action-sheet').someMethod().

Signature Description
show([options]) Show the action sheet.
hide([options]) Hide the action sheet.
show([options]): Promise

Show the action sheet.

Returns:

Parameters
Name Type Description
options Object Parameter object.
options.animation String Animation name. Available animations are "none" and "slide".
options.animationOptions String Specify the animation’s duration, delay and timing. E.g. {duration: 0.2, delay: 0.4, timing: 'ease-in'}.
options.callback Function This function is called after the action sheet has been revealed.
hide([options]): Promise

Hide the action sheet.

Returns: Resolves to the hidden element

Parameters
Name Type Description
options Object Parameter object.
options.animation String Animation name. Available animations are "none" and "slide".
options.animationOptions String Specify the animation’s duration, delay and timing. E.g. {duration: 0.2, delay: 0.4, timing: 'ease-in'}.
options.callback Function This functions is called after the action sheet has been hidden.

Events

To use these events, add event listeners to the elements as you would for native events, like click. For example: document.querySelector('ons-action-sheet').addEventListener('preshow', function() { ... }).

Name Description
preshow Fired just before the action sheet is displayed.
postshow Fired just after the action sheet is displayed.
prehide Fired just before the action sheet is hidden.
posthide Fired just after the action sheet is hidden.
preshow

Fired just before the action sheet is displayed.

Parameters
Name Type Description
event Object Event object.
event.actionSheet Object Component object.
event.cancel Function Execute this function to stop the action sheet from being shown.
postshow

Fired just after the action sheet is displayed.

Parameters
Name Type Description
event Object Event object.
event.actionSheet Object Component object.
prehide

Fired just before the action sheet is hidden.

Parameters
Name Type Description
event Object Event object.
event.actionSheet Object Component object.
event.cancel Function Execute this function to stop the action sheet from being hidden.
posthide

Fired just after the action sheet is hidden.

Parameters
Name Type Description
event Object Event object.
event.actionSheet Object Component object.

Need Help?

If you have any questions, use our Community Forum or talk to us on Discord chat. The Onsen UI team and your peers in the community will work together to help solve your issues.

For bug reports and feature requests use our GitHub Issues page.