Language: ENCN

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 is not recommended to use Action Sheet on large screens (iPad). On large screens you should use Popover instead or Action Sheet To Popover coversion.

Create and open Action Sheet

Action sheet is the dynamic element, it could be created and opened only using JavaScript. Let's look at the related App's method to create Action Sheet:

myApp.actions(groups, animated) - create and open Action Sheet with specified amount of buttons groups
or
myApp.actions(buttons, animated) - create and open Action Sheet with one group and specified buttons

  • groups - array. Array of groups, each group contains array of buttons
  • buttons - array. Array of buttons. In this case there will be one group
  • animated - boolean - Should it be opened with animation or not. Optional. By default is true
  • This method returns dynamically created Action Sheet's HTMLElement

Each Button in buttons should be presented as Object with button parameters:

Parameter Type Default Description
text string String with Button's text (could be HTML string)
bold boolean false Optional. Set to true for bold button text
color string Optional. Button color, one of 10 default colors
bg string Optional. Button background color, one of 10 default colors
label boolean true Optional. If "true" then it will be title instead of button
disabled boolean false Optional. Set to "true" if you want to make button disabled
onClick function Optional. Callback function that will be executed when user click this button

Let's look at examples

 
<body>
  ...
  <div class="page-content">
    <div class="content-block">
      <p><a href="#" class="ac-1">One group, three buttons</a></p>
      <p><a href="#" class="ac-2">One group, title, three buttons</a></p>
      <p><a href="#" class="ac-3">Two groups</a></p>
      <p><a href="#" class="ac-4">Three groups</a></p>
      <p><a href="#" class="ac-5">With callbacks on click</a></p>
    </div>
  </div>
  ...
</body>
var myApp = new Framework7();
 
var $$ = Dom7;
 
//- One group, three buttons
$$('.ac-1').on('click', function () {
    var buttons = [
        {
            text: 'Button1',
            bold: true
        },
        {
            text: 'Button2'
        },
        {
            text: 'Cancel',
            color: 'red'
        },
    ];
    myApp.actions(buttons);
});
 
//- One group, title, three buttons
$$('.ac-2').on('click', function () {
    var buttons = [
        {
            text: 'Do something',
            label: true
        },
        {
            text: 'Button1',
            bold: true
        },
        {
            text: 'Button2',
        },
        {
            text: 'Cancel',
            color: 'red'
        },
    ];
    myApp.actions(buttons);
});
 
//- Two groups
$$('.ac-3').on('click', function () {
    var buttons1 = [
        {
            text: 'Do something',
            label: true
        },
        {
            text: 'Button1',
            bold: true
        },
        {
            text: 'Button2',
        }
    ];
    var buttons2 = [
        {
            text: 'Cancel',
            color: 'red'
        }
    ];
    var groups = [buttons1, buttons2];
    myApp.actions(groups);
});
 
//- Three groups
$$('.ac-4').on('click', function () {
    var buttons1 = [
        {
            text: 'Share',
            label: true
        },
        {
            text: 'Mail',
        },
        {
            text: 'Messages',
        }
    ];
    var buttons2 = [
        {
            text: 'Social share',
            label: true
        },
        {
            text: 'Facebook',
        },
        {
            text: 'Twitter',
        }
    ];
    var buttons3 = [
        {
            text: 'Cancel',
            color: 'red'
        }
    ];
    var groups = [buttons1, buttons2, buttons3];
    myApp.actions(groups);
});
 
//- With callbacks on click
$$('.ac-5').on('click', function () {
    var buttons = [
        {
            text: 'Button1',
            onClick: function () {
                myApp.alert('Button1 clicked');
            }
        },
        {
            text: 'Button2',
            onClick: function () {
                myApp.alert('Button2 clicked');
            }
        },
        {
            text: 'Cancel',
            color: 'red',
            onClick: function () {
                myApp.alert('Cancel clicked');
            }
        },
    ];
    myApp.actions(buttons);
});   

Convert Action Sheet to Popover

Because it is not recommended to use Popover on phones (iPhone) and not recommended to use Action Sheet on tablets (iPad) you can use extended Action Sheet syntax that will convert Action Sheet to Popover automatically on tablets:

myApp.actions(target, groups, animated) - create and open Action Sheet (or Popover on tablets) with specified amount of buttons groups
or
myApp.actions(target, buttons, animated) - create and open Action Sheet (or Popover on tablets) with one group and specified buttons

  • target - HTMLElement or string (with CSS Selector) of target element to set popover position around this element. Requred
  • groups - array. Array of groups, each group contains array of buttons
  • buttons - array. Array of buttons. In this case there will be one group
  • animated - boolean - Should it be opened with animation or not. Optional. By default is true
var myApp = new Framework7();
 
var $$ = Dom7;
 
$$('.something').on('click', function (e) {
    var target = this;
    var buttons = [
        {
            text: 'Button 1'
        },
        {
            text: 'Button 2'
        }
    ];
    myApp.actions(target, buttons);
});

Close Action Sheet

By default, Action sheet will be automatically closed when:

  • you click one of its buttons
  • you click outside its window on overlay (configurable via modalActionsCloseByOutside App initialization parameter)

To close Action sheet manually we can use appropriate App's method:

myApp.closeModal(actionSheet) - close Popup

  • actionSheet - HTMLElement or string (with CSS Selector) of Action sheet to be closed. Optional. If not specified, any opened Action sheet will be closed

Action Sheet Events

Action Sheet has the same events as any Modal

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

Action Sheet Template

If you want to customize Action Sheet template, you may customize it by passing modalActionsTemplate parameter on App initialization. This parameter accepts Template7 formatted HTML string that will be compiled by Template7 with passed groups context.

So the acceptable template could look like:

<!-- This template equalt to default layout -->
<div class="actions-modal">
  <!-- this is a single group -->
  {{#each this}}
    <div class="actions-modal-group">
      <!-- now this represents a single button -->
      {{#each this}}
          {{#if label}}
            <span class="actions-modal-label">{{text}}</span>
          {{else}}
            <div class="actions-modal-button {{#if color}}color-{{color}}{{/if}} {{#if bold}}actions-modal-button-bold{{/if}}">{{text}}</div>
          {{/if}}
      {{/each}}
    </div>
  {{/each}}
</div>            

Action Sheet To Popover Template

If you use convertation of Action Sheet to Popover, then you may customize Popover template by passing modalActionsToPopoverTemplate parameter on App initialization. This parameter accepts Template7 formatted HTML string that will be compiled by Template7 with passed groups context.

Here is the default template:

<div class="popover actions-popover">
  <div class="popover-inner">
    {{#each this}}
    <div class="list-block">
      <ul>
        {{#each this}}
        {{#if label}}
        <li class="actions-popover-label {{#if color}}color-{{color}}{{/if}} {{#if bold}}actions-popover-bold{{/if}}">{{text}}</li>
        {{else}}
        <li><a href="#" class="item-link list-button {{#if color}}color-{{color}}{{/if}} {{#if bg}}bg-{{bg}}{{/if}} {{#if bold}}actions-popover-bold{{/if}} {{#if disabled}}disabled{{/if}}">{{text}}</a></li>
        {{/if}}
        {{/each}}
      </ul>
    </div>
    {{/each}}
  </div>
</div>