Sheet Modal

Sheet Modal is a special overlay type which is similar to Picker/Calendar's overlay. Such modal allows to create custom overlays with custom content

Sheet Layout

Sheet layout is pretty simple:

<body>
  ...
  <!-- Sheet Modal Container -->
  <div class="sheet-modal">
    <!-- Sheet Modal Toolbar, optional -->
    <div class="toolbar">
      <div class="toolbar-inner">
        <div class="left"></div>
        <div class="right">
          <a href="#" class="link sheet-close">Done</a>
        </div>
      </div>
    </div>
    <!-- Sheet Modal Inner -->
    <div class="sheet-modal-inner">
      <!-- Sheet Modal content -->
      <div class="block">
        <p>Integer mollis nulla id nibh elementum finibus...</p>
      </div>
    </div>
  </div>

</body>

Sheet App Methods

Let's look at related App methods to work with Sheet:

app.sheet.create(parameters)- create Sheet instance

  • parameters - object. Object with sheet parameters

Method returns created Sheet's instance

app.sheet.destroy(el)- destroy Sheet instance

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

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

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

Method returns Sheet's instance

app.sheet.open(el, animate)- opens Sheet

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

Method returns Sheet's instance

app.sheet.close(el, animate)- closes Sheet

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

Method returns Sheet's instance

Sheet Parameters

Now let's look at list of available parameters we need to create Sheet:

ParameterTypeDefaultDescription
elHTMLElementSheet element. Can be useful if you already have Sheet element in your HTML and want to create new instance using this element
contentstringFull Sheet HTML layout string. Can be useful if you want to create Sheet element dynamically
backdropbooleanEnables Sheet backdrop (dark semi transparent layer behind). By default it is true for MD theme and false for iOS theme
scrollToElHTMLElement
string
HTML element or string (with CSS selector) of element. If specified, then sheet will try to scroll page content to this element on open
closeByBackdropClickbooleantrueWhen enabled, sheet will be closed on backdrop click
closeByOutsideClickbooleanfalseWhen enabled, sheet will be closed on when click outside of it
animatebooleantrueWhether the Sheet should be opened/closed with animation or not. Can be overwritten in .open() and .close() methods
onobjectObject with events handlers. For example:
var sheet = app.sheet.create({
  content: '<div class="sheet-modal">...</div>',
  on: {
    opened: function () {
      console.log('Sheet opened')
    }
  }
})

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

var app = new Framework7({
  sheet: {
    closeByBackdropClick: false,
  }
});

Sheet Methods & Properties

So to create Sheet we have to call:

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

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

Properties
sheet.appLink to global app instance
sheet.elSheet HTML element
sheet.$elDom7 instance with sheet HTML element
sheet.backdropElBackdrop HTML element
sheet.$backdropElDom7 instance with backdrop HTML element
sheet.paramsSheet parameters
sheet.openedBoolean prop indicating whether sheet is opened or not
Methods
sheet.open(animate)Open sheet. Where
  • animate - boolean (by default true) - defines whether it should be opened with animation
sheet.close(animate)Close sheet. Where
  • animate - boolean (by default true) - defines whether it should be closed with animation
sheet.destroy()Destroy sheet
sheet.on(event, handler)Add event handler
sheet.once(event, handler)Add event handler that will be removed after it was fired
sheet.off(event, handler)Remove event handler
sheet.off(event)Remove all handlers for specified event
sheet.emit(event, ...args)Fire event on instance

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

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

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

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

According to above note:

<!-- In data-sheet attribute we specify CSS selector of sheet we need to open -->
<p><a href="#" data-sheet=".my-sheet" class="sheet-open">Open Sheet</a></p>

<!-- And somewhere in DOM -->
<div class="sheet-modal my-sheet">
  <div class="sheet-modal-inner">
    <!-- Link to close sheet -->
    <a class="link sheet-close">Close</a>
  </div>
</div>

Sheet Events

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

DOM Events

EventTargetDescription
sheet:openSheet Element<div class="sheet">Event will be triggered when Sheet starts its opening animation
sheet:openedSheet Element<div class="sheet">Event will be triggered after Sheet completes its opening animation
sheet:closeSheet Element<div class="sheet">Event will be triggered when Sheet starts its closing animation
sheet:closedSheet Element<div class="sheet">Event will be triggered after Sheet completes its closing animation

App and Sheet Instance Events

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

EventArgumentsTargetDescription
opensheetsheetEvent will be triggered when Sheet starts its opening animation. As an argument event handler receives sheet instance
sheetOpensheetapp
openedsheetsheetEvent will be triggered after Sheet completes its opening animation. As an argument event handler receives sheet instance
sheetOpenedsheetapp
closesheetsheetEvent will be triggered when Sheet starts its closing animation. As an argument event handler receives sheet instance
sheetClosesheetapp
closedsheetsheetEvent will be triggered after Sheet completes its closing animation. As an argument event handler receives sheet instance
sheetClosedsheetapp
beforeDestroysheetsheetEvent will be triggered right before Sheet instance will be destroyed. As an argument event handler receives sheet instance
sheetBeforeDestroysheetapp

CSS Variables

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

:root {
  --f7-sheet-height: 260px;
}
.ios {
  --f7-sheet-bg-color: #cfd5da;
  --f7-sheet-border-color: #929499;
}
.ios .theme-dark,
.ios.theme-dark {
  --f7-sheet-bg-color: #171717;
  --f7-sheet-border-color: var(--f7-bars-border-color);
}
.md {
  --f7-sheet-bg-color: #fff;
  --f7-sheet-border-color: transparent;
}
.md .theme-dark,
.md.theme-dark {
  --f7-sheet-bg-color: #202020;
  --f7-sheet-border-color: transparent;
}

Examples

<body>
  ...
    <div class="page">
      <div class="navbar">
        <div class="navbar-inner">
          <!-- In data-sheet attribute we specify CSS selector of sheet we need to open-->
          <div class="title">Sheet Modal</div>
          <div class="right"><a class="link sheet-open" href="#" data-sheet=".my-sheet">Open Sheet</a></div>
        </div>
      </div>
      <div class="page-content">
        <div class="block">
          <!-- In data-sheet attribute we specify CSS selector of sheet we need to open-->
          <p><a class="link sheet-open" href="#" data-sheet=".my-sheet">Open Sheet</a></p>
          <!-- Link to close sheet-->
          <p><a class="link sheet-close" href="#" data-sheet=".my-sheet">Close Sheet</a></p>
          <p><a class="link dynamic-sheet" href="#">Create Dynamic Sheet</a></p>
        </div>
      </div>
    </div>
  ...

  <div class="sheet-modal my-sheet">
    <div class="toolbar">
      <div class="toolbar-inner">
        <div class="left"></div>
        <div class="right"><a class="link sheet-close" href="#">Done</a></div>
      </div>
    </div>
    <div class="sheet-modal-inner">
      <div class="block">
        <h4>Info</h4>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque ac diam ac quam euismod porta vel a nunc. Quisque sodales scelerisque est, at porta justo cursus ac.</p>
      </div>
    </div>
  </div>
</body>
var app = new Framework7();

var $$ = Dom7;

// DOM events for my-sheet sheet
$$('.my-sheet').on('sheet:open', function (e, sheet) {
  console.log('my-sheet open');
});
$$('.my-sheet').on('sheet:opened', function (e, sheet) {
  console.log('my-sheet opened');
});

// Create dynamic Sheet
var dynamicSheet = app.sheet.create({
  content: '<div class="sheet-modal">'+
              '<div class="toolbar">'+
                '<div class="toolbar-inner">'+
                  '<div class="left"></div>'+
                  '<div class="right">'+
                    '<a class="link sheet-close">Done</a>'+
                  '</div>'+
                '</div>'+
              '</div>'+
              '<div class="sheet-modal-inner">'+
                '<div class="block">'+
                  '<p>Sheet created dynamically.</p>'+
                  '<p><a href="#" class="link sheet-close">Close me</a></p>'+
                '</div>'+
              '</div>'+
            '</div>',
  // Events
  on: {
    open: function (sheet) {
      console.log('Sheet open');
    },
    opened: function (sheet) {
      console.log('Sheet opened');
    },
  }
});
// Events also can be assigned on instance later
dynamicSheet.on('close', function (sheet) {
  console.log('Sheet close');
});
dynamicSheet.on('closed', function (sheet) {
  console.log('Sheet closed');
});

// Open dynamic sheet
$$('.dynamic-sheet').on('click', function () {
  // Close inline sheet before
  app.sheet.close('.my-sheet');

  // Open dynamic sheet
  dynamicSheet.open();
});