Action Sheet

    Action Sheet is a slide-up pane for presenting the user with a set of alternatives for how to proceed with a given task.

    You can also use action sheets to prompt the user to confirm a potentially dangerous action.

    The action sheet contains an optional title and one or more buttons, each of which corresponds to an action to take.

    Note that it is not recommended to use Action Sheet on large screens (iPad). On large screens you should use Popover instead.

    Action Sheet App Methods

    Lets look at related App methods to work with the Action Sheet:

    app.actions.create(parameters)- create Action Sheet instance

    • parameters - object. Object with action sheet parameters

    Method returns created Action Sheet's instance

    app.actions.destroy(el)- destroy Action Sheet instance

    • el - HTMLElement or string (with CSS Selector) or object. Action element instance to destroy.

    app.actions.get(el)- get Action Sheet instance by HTML element

    • el - HTMLElement or string (with CSS Selector). Action Sheet element.

    Method returns Action Sheet's instance

    app.actions.open(el, animate)- opens Action Sheet

    • el - HTMLElement or string (with CSS Selector). Action Sheet element to open.
    • animate - boolean. Open Actions Sheet with animation.

    Method returns Action Sheet's instance

    app.actions.close(el, animate)- closes Action Sheet

    • el - HTMLElement or string (with CSS Selector). Action Sheet element to close.
    • animate - boolean. Close Actions Sheet with animation.

    Method returns Action Sheet's instance

    Action Sheet Parameters

    Now lets look at a list of available parameters we need to create the Action Sheet:

    Parameter Type Default Description
    el HTMLElement Action Sheet element. Can be useful if you already have Action Sheet element in your HTML and want to create new instance using this element
    content string Full Action Sheet HTML content string. Can be useful if you want to create Action Sheet element with custom HTML
    backdrop boolean true Enables Action Sheet backdrop (dark semi transparent layer behind)
    closeByBackdropClick boolean true When enabled, action sheet will be closed on backdrop click
    closeByOutsideClick boolean false When enabled, action sheet will be closed on when click outside of it
    animate boolean true Whether the Action Sheet should be opened/closed with animation or not. Can be overwritten in .open() and .close() methods
    buttons array Action sheet groups/buttons. In this case Actions layout will be generated dynamically based on passed groups and buttons. In case of groups it should array where each item represent array with buttons for group.
    grid boolean false Enables grid buttons layout
    convertToPopover boolean true When enabled, action sheet will be converted to Popover on large screens.
    forceToPopover boolean false When enabled, action sheel will be always converted to Popover.
    targetEl HTMLElement
    string
    HTML element or string CSS selector of target element. Required when converstion to popover is in use
    targetX number Virtual target element horizontal offset from left side of the screen. Required when converstion to popover is in use without using real target element (targetEl)
    targetY number Virtual target element vertical offset from top of the screen. Required when converstion to popover is in use without using real target element (targetEl)
    targetWidth number 0 Virtual target element width (in px). Required when converstion to popover is in use without using real target element (targetEl)
    targetHeight number 0 Virtual target element height (in px). Required when converstion to popover is in use without using real target element (targetEl)
    onClick function(actions, e) Callback function that will be executed after click on the Action Sheet button
    render function Custom function to render Action Sheet. Must return Action Sheet html
    renderPopover function Custom function to render Popover when conversition to popover is in use. Must return Popover html
    on object Object with events handlers. For example:
    var actions = app.actions.create({
      buttons: [ /* ... */ ],
      on: {
        opened: function () {
          console.log('Action Sheet opened')
        }
      }
    })

    Note that all of the following parameters can be used in the global app parameters under the actions property to set defaults for all action sheets. For example:

    var app = new Framework7({
      actions: {
        convertToPopover: false,
        grid: true,
      }
    });

    Button Parameters

    Each Button in buttons array must be presented as an object with button parameters:

    Parameter Type Default Description
    text string String with Button's text (could be HTML string)
    icon string HTML string of icon
    bold boolean false Enables bold button text
    color string Button color, one of default colors
    bg string Button background color, one of default colors
    label boolean false If enabled then it will be rendered as label instead of button
    disabled boolean false Defines whether the button is disabled or not.
    close boolean true If enabled then button click will close Action Sheet
    onClick function(actions, e) Callback function that will be executed after click on this button

    Action Sheet Methods & Properties

    So to create an Action Sheet we have to call:

    var actions = app.actions.create({ /* parameters */ })

    After that we have its initialized instance (like actions variable in example above) with useful methods and properties:

    Properties
    actions.app Link to global app instance
    actions.el Action sheet HTML element
    actions.$el Dom7 instance with action sheet HTML element
    actions.backdropEl Backdrop HTML element
    actions.$backdropEl Dom7 instance with backdrop HTML element
    actions.params Action sheet instance parameters
    actions.opened Boolean prop indicating whether action sheet is opened or not
    Methods
    actions.open(animate) Open action sheet. Where
    • animate - boolean (by default true) - defines whether it should be opened with animation
    actions.close(animate) Close action sheet. Where
    • animate - boolean (by default true) - defines whether it should be closed with animation
    actions.destroy() Destroy action sheet
    actions.on(event, handler) Add event handler
    actions.once(event, handler) Add event handler that will be removed after it was fired
    actions.off(event, handler) Remove event handler
    actions.off(event) Remove all handlers for specified event
    actions.emit(event, ...args) Fire event on instance

    Control Action Sheet With Links

    It is possible to open and close required action sheets (if you have them in DOM) using special classes and data attributes on links:

    • To open action sheet we need to add "actions-open" class to any HTML element (prefered to link)

    • To close action sheet we need to add "actions-close" class to any HTML element (prefered to link)

    • If you have more than one action sheet in DOM, you need to specify appropriate action sheet via additional data-actions=".my-actions" attribute on this HTML element

    According to above note:

    <!-- In data-actions attribute we specify CSS selector of action sheet we need to open -->
    <p><a href="#" data-actions=".my-actions" class="actions-open">Open Actions</a></p>
    
    <!-- And somewhere in DOM -->
    <div class="actions-modal my-actions">
      ...
    </div>
    
    

    Action Sheet Events

    Action sheet will fire the following DOM events on action sheet element and events on app and action sheet instance:

    DOM Events

    Event Target Description
    actions:open Action Sheet Element<div class="actions-modal"> Event will be triggered when Action Sheet starts its opening animation
    actions:opened Action Sheet Element<div class="actions-modal"> Event will be triggered after Action Sheet completes its opening animation
    actions:close Action Sheet Element<div class="actions-modal"> Event will be triggered when Action Sheet starts its closing animation
    actions:closed Action Sheet Element<div class="actions-modal"> Event will be triggered after Action Sheet completes its closing animation

    App and Action Sheet Instance Events

    Action Sheet instance emits events on both self instance and app instance. App instance events has same names prefixed with actions.

    Event Arguments Target Description
    open actions actions Event will be triggered when Action Sheet starts its opening animation. As an argument event handler receives action sheet instance
    actionsOpen actions app
    opened actions actions Event will be triggered after Action Sheet completes its opening animation. As an argument event handler receives action sheet instance
    actionsOpened actions app
    close actions actions Event will be triggered when Action Sheet starts its closing animation. As an argument event handler receives action sheet instance
    actionsClose actions app
    closed actions actions Event will be triggered after Action Sheet completes its closing animation. As an argument event handler receives action sheet instance
    actionsClosed actions app
    beforeDestroy actions actions Event will be triggered right before Action Sheet instance will be destroyed. As an argument event handler receives action sheet instance
    actionsBeforeDestroy actions app

    Examples

    <body>
    ...
     <div class="page-content">
      <div class="block">
        <p><a class="ac-1" href="#">One group, three buttons</a></p>
        <p><a class="ac-2" href="#">One group, title, three buttons</a></p>
        <p><a class="ac-3" href="#">Two groups</a></p>
        <p><a class="ac-4" href="#">Three groups</a></p>
        <p><a class="ac-5" href="#">With callbacks on click</a></p>
        <p><a class="ac-6" href="#">Actions grid</a></p>
      </div>
    </div>
    ...
    </body>
    
    var app = new Framework7();
    
    var $$ = Dom7;
    
    //- One group, three buttons
    var ac1 = app.actions.create({
      buttons: [
        {
          text: 'Button1',
          bold: true
        },
        {
          text: 'Button2'
        },
        {
          text: 'Cancel',
          color: 'red'
        },
      ]
    })
    //- One group, title, three buttons
    var ac2 = app.actions.create({
      buttons: [
        {
          text: 'Do something',
          label: true
        },
        {
          text: 'Button1',
          bold: true
        },
        {
          text: 'Button2',
        },
        {
          text: 'Cancel',
          color: 'red'
        },
      ]
    });
    //- Two groups
    var ac3 = app.actions.create({
      buttons: [
        // First group
        [
          {
            text: 'Do something',
            label: true
          },
          {
            text: 'Button1',
            bold: true
          },
          {
            text: 'Button2',
          }
        ],
        // Second group
        [
          {
            text: 'Cancel',
            color: 'red'
          }
        ]
      ]
    });
    //- Three groups
    var ac4 = app.actions.create({
      buttons: [
        [
          {
            text: 'Share',
            label: true
          },
          {
            text: 'Mail',
          },
          {
            text: 'Messages',
          }
        ],
        [
          {
            text: 'Social share',
            label: true
          },
          {
            text: 'Facebook',
          },
          {
            text: 'Twitter',
          }
        ],
        [
          {
            text: 'Cancel',
            color: 'red'
          }
        ]
      ],
    });
    //- With callbacks on click
    var ac5 = app.actions.create({
      buttons: [
        {
          text: 'Button1',
          onClick: function () {
            app.dialog.alert('Button1 clicked')
          }
        },
        {
          text: 'Button2',
          onClick: function () {
            app.dialog.alert('Button2 clicked')
          }
        },
        {
          text: 'Cancel',
          color: 'red',
          onClick: function () {
            app.dialog.alert('Cancel clicked')
          }
        },
      ]
    });
    //- Actions Grid
    var ac6 = app.actions.create({
      grid: true,
      buttons: [
        [
          {
            text: 'Button 1',
            icon: '<img src="http://lorempixel.com/96/96/people/1" width="48"/>'
          },
          {
            text: 'Button 2',
            icon: '<img src="http://lorempixel.com/96/96/people/2" width="48">'
          },
          {
            text: 'Button 3',
            icon: '<img src="http://lorempixel.com/96/96/people/3" width="48">'
          },
        ],
        [
          {
            text: 'Button 1',
            icon: '<img src="http://lorempixel.com/96/96/fashion/4" width="48"/>'
          },
          {
            text: 'Button 2',
            icon: '<img src="http://lorempixel.com/96/96/fashion/5" width="48">'
          },
          {
            text: 'Button 3',
            icon: '<img src="http://lorempixel.com/96/96/fashion/6" width="48">'
          },
        ]
      ]
    });
    
    $$('.ac-1').on('click', function () {
        ac1.open();
    });
    $$('.ac-2').on('click', function () {
        ac2.open();
    });
    $$('.ac-3').on('click', function () {
        ac3.open();
    });
    $$('.ac-4').on('click', function () {
        ac4.open();
    });
    $$('.ac-5').on('click', function () {
        ac5.open();
    });
    $$('.ac-6').on('click', function () {
        ac6.open();
    });