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:

ParameterTypeDefaultDescription
elHTMLElement
string
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
contentstringFull Action Sheet HTML content string. Can be useful if you want to create Action Sheet element with custom HTML
backdropbooleantrueEnables Action Sheet backdrop (dark semi transparent layer behind)
backdropElHTMLElement
string
HTML element or string CSS selector of custom backdrop element
backdropUniquebooleanfalseIf enabled it creates unique backdrop element exclusively for this modal
closeByBackdropClickbooleantrueWhen enabled, action sheet will be closed on backdrop click
closeByOutsideClickbooleanfalseWhen enabled, action sheet will be closed on when click outside of it
closeOnEscapebooleanfalseWhen enabled, action sheet will be closed on ESC keyboard key press
animatebooleantrueWhether the Action Sheet should be opened/closed with animation or not. Can be overwritten in .open() and .close() methods
buttonsarrayAction 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.
gridbooleanfalseEnables grid buttons layout
convertToPopoverbooleantrueWhen enabled, action sheet will be converted to Popover on large screens.
forceToPopoverbooleanfalseWhen enabled, action sheet will be always converted to Popover.
targetElHTMLElement
string
HTML element or string CSS selector of target element. Required when conversion to popover is in use
targetXnumberVirtual target element horizontal offset from left side of the screen. Required when conversion to popover is in use without using real target element (targetEl)
targetYnumberVirtual target element vertical offset from top of the screen. Required when conversion to popover is in use without using real target element (targetEl)
targetWidthnumber0Virtual target element width (in px). Required when conversion to popover is in use without using real target element (targetEl)
targetHeightnumber0Virtual target element height (in px). Required when conversion to popover is in use without using real target element (targetEl)
cssClassstringAdditional CSS class name to be set on action sheet element
onClickfunction(actions, e)Callback function that will be executed after click on the Action Sheet button
renderfunctionCustom function to render Action Sheet. Must return Action Sheet html
renderPopoverfunctionCustom function to render Popover when conversion to popover is in use. Must return Popover html
containerElHTMLElement
string
Element to mount modal to (default to app root element)
onobject

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:

ParameterTypeDefaultDescription
textstringString with Button's text (could be HTML string)
iconstringHTML string of icon
strongbooleanfalseEnables bold button text
colorstringButton color, one of default colors
bgstringButton background color, one of default colors
labelbooleanfalseIf enabled then it will be rendered as label instead of button
disabledbooleanfalseDefines whether the button is disabled or not.
closebooleantrueIf enabled then button click will close Action Sheet
onClickfunction(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.appLink to global app instance
actions.elAction sheet HTML element
actions.$elDom7 instance with action sheet HTML element
actions.backdropElBackdrop HTML element
actions.$backdropElDom7 instance with backdrop HTML element
actions.paramsAction sheet instance parameters
actions.openedBoolean 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

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 (preferred to link)

  • To close action sheet we need to add "actions-close" class to any HTML element (preferred 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

EventTargetDescription
actions:openAction Sheet Element<div class="actions-modal">Event will be triggered when Action Sheet starts its opening animation
actions:openedAction Sheet Element<div class="actions-modal">Event will be triggered after Action Sheet completes its opening animation
actions:closeAction Sheet Element<div class="actions-modal">Event will be triggered when Action Sheet starts its closing animation
actions:closedAction 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.

EventArgumentsTargetDescription
openactionsactionsEvent will be triggered when Action Sheet starts its opening animation. As an argument event handler receives action sheet instance
actionsOpenactionsapp
openedactionsactionsEvent will be triggered after Action Sheet completes its opening animation. As an argument event handler receives action sheet instance
actionsOpenedactionsapp
closeactionsactionsEvent will be triggered when Action Sheet starts its closing animation. As an argument event handler receives action sheet instance
actionsCloseactionsapp
closedactionsactionsEvent will be triggered after Action Sheet completes its closing animation. As an argument event handler receives action sheet instance
actionsClosedactionsapp
beforeDestroyactionsactionsEvent will be triggered right before Action Sheet instance will be destroyed. As an argument event handler receives action sheet instance
actionsBeforeDestroyactionsapp

CSS Variables

Below is the list of related CSS variables (CSS custom properties).

Note that commented variables are not specified by default and their values is what they fallback to in this case.

:root {
  --f7-actions-grid-button-font-size: 12px;
  --f7-actions-grid-button-icon-size: 48px;
}
.ios {
  --f7-actions-transition-timing-function: initial;
  --f7-actions-border-radius: 13px;
  /*
  --f7-actions-button-text-color: var(--f7-theme-color);
  */
  --f7-actions-grid-button-text-color: #757575;
  --f7-actions-button-padding: 0px;
  --f7-actions-button-text-align: center;
  --f7-actions-button-height: 57px;
  --f7-actions-button-height-landscape: 44px;
  --f7-actions-button-font-size: 20px;
  --f7-actions-button-icon-size: 28px;
  --f7-actions-button-justify-content: center;
  --f7-actions-label-padding: 8px 10px;
  --f7-actions-label-font-weight: 400;
  --f7-actions-label-font-size: 13px;
  --f7-actions-label-justify-content: center;
  --f7-actions-group-border-color: transparent;
  --f7-actions-group-margin: 8px;
  --f7-actions-bg-color: rgba(255, 255, 255, 0.95);
  --f7-actions-bg-color-rgb: 255, 255, 255;
  --f7-actions-button-border-color: rgba(0, 0, 0, 0.2);
  --f7-actions-button-pressed-bg-color: rgba(230, 230, 230, 0.9);
  --f7-actions-button-pressed-bg-color-rgb: 230, 230, 230;
  --f7-actions-label-text-color: #8a8a8a;
}
.ios .dark,
.ios.dark {
  --f7-actions-bg-color: rgba(45, 45, 45, 0.95);
  --f7-actions-bg-color-rgb: 45, 45, 45;
  --f7-actions-button-border-color: rgba(255, 255, 255, 0.15);
  --f7-actions-button-pressed-bg-color: rgba(50, 50, 50, 0.9);
  --f7-actions-button-pressed-bg-color-rgb: 50, 50, 50;
  --f7-actions-label-text-color: rgba(255, 255, 255, 0.55);
}
.md {
  --f7-actions-transition-timing-function: cubic-bezier(0, 0.8, 0.34, 1);
  --f7-actions-border-radius: 16px;
  --f7-actions-button-border-color: transparent;
  --f7-actions-button-padding: 0 16px;
  --f7-actions-button-text-align: left;
  --f7-actions-button-height: 48px;
  --f7-actions-button-height-landscape: 48px;
  --f7-actions-button-font-size: 16px;
  --f7-actions-button-icon-size: 24px;
  --f7-actions-button-justify-content: space-between;
  --f7-actions-label-padding: 12px 16px;
  --f7-actions-label-font-size: 14px;
  --f7-actions-label-font-weight: 500;
  --f7-actions-label-justify-content: flex-start;
  --f7-actions-group-margin: 0px;
  --f7-actions-button-pressed-bg-color: #e5e5e5;
}
.md .dark,
.md.dark {
  --f7-actions-button-pressed-bg-color: #2e2e2e;
}
.md,
.md .dark,
.md [class*='color-'] {
  --f7-actions-button-text-color: var(--f7-md-on-surface);
  --f7-actions-bg-color: var(--f7-md-surface-3);
  --f7-actions-group-border-color: var(--f7-md-outline);
  --f7-actions-label-text-color: var(--f7-theme-color);
  --f7-actions-grid-button-text-color: var(--f7-md-on-surface);
}

Examples

action-sheet.html
<template>
  <div class="page">
    <div class="navbar">
      <div class="navbar-bg"></div>
      <div class="navbar-inner sliding">
        <div class="title">Action Sheet</div>
      </div>
    </div>
    <div class="page-content">
      <div class="block block-strong inset">
        <p class="grid grid-cols-2 grid-gap">
          <a class="button button-fill" @click=${openDemo1}>One group</a>
          <a class="button button-fill" @click=${openDemo2}>Two groups</a>
        </p>
        <p>
          <a class="button button-fill" @click=${openGrid}>Action Grid</a>
        </p>
      </div>
      <div class="block-title">Action Sheet To Popover</div>
      <div class="block block-strong inset">
        <p>Action Sheet can be automatically converted to Popover (for tablets). This button will open Popover on
          tablets and Action Sheet on phones: <a style="display:inline-block"
            class="button button-to-popover button-small" @click=${openActionsPopover}>Actions</a></p>
      </div>
    </div>
  </div>
</template>
<script>
  export default (props, { $on, $f7, $el }) => {
    let actions1;
    let actions2;
    let actionsGrid;
    let actionsToPopover;

    const openDemo1 = () => {
      actions1.open();
    }
    const openDemo2 = () => {
      actions2.open();
    }
    const openGrid = () => {
      actionsGrid.open();
    }
    const openActionsPopover = () => {
      actionsToPopover.open();
    }

    $on('pageInit', () => {
      // 1 Group
      const buttons1 = [
        {
          text: 'Do something',
          label: true
        },
        {
          text: 'Button 1',
          strong: true
        },
        {
          text: 'Button 2',
        },
        {
          text: 'Cancel',
          color: 'red'
        },
      ];

      // 2 Groups
      const buttons2 = [
        // First Group
        [
          {
            text: 'Do something',
            label: true
          },
          {
            text: 'Button 1',
            strong: true
          },
          {
            text: 'Button 2',
          }
        ],
        // Second Group
        [
          {
            text: 'Cancel',
            color: 'red'
          }
        ]
      ]

      // Grid buttons with icons/images
      const gridButtons = [
        [
          {
            text: 'Button 1',
            icon: '<img src="https://cdn.framework7.io/placeholder/people-96x96-1.jpg" width="48" style="max-width: 100%; border-radius: 8px"/>'
          },
          {
            text: 'Button 2',
            icon: '<img src="https://cdn.framework7.io/placeholder/people-96x96-2.jpg" width="48" style="max-width: 100%; border-radius: 8px">'
          },
          {
            text: 'Button 3',
            icon: '<img src="https://cdn.framework7.io/placeholder/people-96x96-3.jpg" width="48" style="max-width: 100%; border-radius: 8px">'
          },
        ],
        [
          {
            text: 'Button 1',
            icon: '<img src="https://cdn.framework7.io/placeholder/fashion-96x96-4.jpg" width="48" style="max-width: 100%; border-radius: 8px"/>'
          },
          {
            text: 'Button 2',
            icon: '<img src="https://cdn.framework7.io/placeholder/fashion-96x96-5.jpg" width="48" style="max-width: 100%; border-radius: 8px">'
          },
          {
            text: 'Button 3',
            icon: '<img src="https://cdn.framework7.io/placeholder/fashion-96x96-6.jpg" width="48" style="max-width: 100%; border-radius: 8px">'
          },
        ],
      ]

      actions1 = $f7.actions.create({ buttons: buttons1 });
      actions2 = $f7.actions.create({ buttons: buttons2 });
      actionsGrid = $f7.actions.create({ buttons: gridButtons, grid: true });

      // Actions To Popover
      actionsToPopover = $f7.actions.create({
        buttons: buttons1,
        // Need to specify popover target
        targetEl: $el.value.find('.button-to-popover')
      });
    })

    $on('pageBeforeRemove', () => {
      actions1.destroy();
      actions2.destroy();
      actionsGrid.destroy();
      actionsToPopover.destroy();
    })

    return $render;
  }

</script>