Dialog

Dialog is a small content pane that pops up over App's main content. Dialogs are usualy used to ask something from a user, or to notify or warn a user. Dialog, as all other modals, is part of so called "Temporary Views".

Dialog can only be opened by using JavaScript. So lets look at related App methods to work with dialogs.

Dialog App Methods

Lets look at related App methods to work with Dialog:

app.dialog.create(parameters)- create Dialog instance

  • parameters - object. Object with dialog parameters

Method returns created Dialog's instance

app.dialog.destroy(el)- destroy Dialog instance

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

app.dialog.get(el)- get Dialog instance by HTML element

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

Method returns Dialog's instance

app.dialog.open(el, animate)- opens Dialog

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

Method returns Dialog's instance

app.dialog.close(el, animate)- closes Dialog

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

Method returns Dialog's instance

Dialog Parameters

Now lets look at list of available parameters we need to create Dialog:

ParameterTypeDefaultDescription
elHTMLElement
string
Dialog element. Can be useful if you already have Dialog element in your HTML and want to create new instance using this element
containerElHTMLElement
string
Allows to mount the dialog to custom element rather than app root element (app.el)
backdropbooleantrueEnables Dialog backdrop (dark semi transparent layer behind)
closeByBackdropClickbooleanfalseWhen enabled, dialog will be closed on backdrop click
animatebooleantrueWhether the Dialog should be opened/closed with animation or not. Can be overwritten in .open() and .close() methods
titlestringDialog title
textstringDialog inner text
contentstringCustom Dialog content that follows dialog text. Can accept any HTML content
buttonsarray[]Array with dialog buttons, where each button is an object with Button Parameters
verticalButtonsbooleanfalseEnables vertical buttons layout
destroyOnClosebooleanfalseWhen enabled will automatically destroy Dialog on close
onClickfunction(dialog, index)Callback function that will be executed after click on the Dialog button. As an arguments it received dialog instance and clicked button index number
cssClassstringAdditional css class to add
onobject

Object with events handlers. For example:

var dialog = app.dialog.create({
  text: 'Hello World',
  on: {
    opened: function () {
      console.log('Dialog opened')
    }
  }
})

Button Parameters

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

ParameterTypeDefaultDescription
textstringString with Button's text (could be HTML string)
strongbooleanfalseEnables bold button text
colorstringButton color, one of default colors
closebooleantrueIf enabled then button click will close Dialog
cssClassstringAdditional button CSS class
keyCodesarray[]Array with keyboard keycodes that will be used to trigger button click. For example, key code 13 means that button click will be triggered on Enter key press
onClickfunction(dialog, e)Callback function that will be executed after click on this button

Dialog Methods & Properties

So to create a Dialog we have to call:

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

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

Properties
dialog.appLink to global app instance
dialog.elDialog HTML element
dialog.$elDom7 instance with dialog HTML element
dialog.backdropElBackdrop HTML element
dialog.$backdropElDom7 instance with backdrop HTML element
dialog.paramsDialog parameters
dialog.openedBoolean prop indicating whether dialog is opened or not
Methods
dialog.open(animate)Open dialog. Where
  • animate - boolean (by default true) - defines whether it should be opened with animation
dialog.close(animate)Close dialog. Where
  • animate - boolean (by default true) - defines whether it should be closed with animation
dialog.setProgress(progress, duration)Sets dialog progress when Dialog Progress shortcut in use
  • progress - number - progressbar progress (from 0 to 100)
  • duration - number (in ms) - progressbar progress change duration
dialog.setTitle(title)Sets dialog's title
  • title - string - new dialog title
dialog.setText(text)Sets dialog's text
  • text - string - new dialog text
dialog.destroy()Destroy dialog
dialog.on(event, handler)Add event handler
dialog.once(event, handler)Add event handler that will be removed after it was fired
dialog.off(event, handler)Remove event handler
dialog.off(event)Remove all handlers for specified event
dialog.emit(event, ...args)Fire event on instance

Dialog Events

Dialog will fire the following DOM events on dialog element and events on app and dialog instance:

DOM Events

EventTargetDescription
dialog:openDialog Element<div class="dialog">Event will be triggered when Dialog starts its opening animation
dialog:openedDialog Element<div class="dialog">Event will be triggered after Dialog completes its opening animation
dialog:closeDialog Element<div class="dialog">Event will be triggered when Dialog starts its closing animation
dialog:closedDialog Element<div class="dialog">Event will be triggered after Dialog completes its closing animation
dialog:beforedestroyDialog Element<div class="dialog">Event will be triggered right before Dialog instance will be destroyed

App and Dialog Instance Events

Dialog instance emits events on both self instance and app instance. App instance events has same names prefixed with dialog.

EventArgumentsTargetDescription
opendialogdialogEvent will be triggered when Dialog starts its opening animation. As an argument event handler receives dialog instance
dialogOpendialogapp
openeddialogdialogEvent will be triggered after Dialog completes its opening animation. As an argument event handler receives dialog instance
dialogOpeneddialogapp
closedialogdialogEvent will be triggered when Dialog starts its closing animation. As an argument event handler receives dialog instance
dialogClosedialogapp
closeddialogdialogEvent will be triggered after Dialog completes its closing animation. As an argument event handler receives dialog instance
dialogCloseddialogapp
beforeDestroydialogdialogEvent will be triggered right before Dialog instance will be destroyed. As an argument event handler receives dialog instance
dialogBeforeDestroydialogapp

Dialog Shortcuts

There are a few shortcut methods which that make creating dialogs much easier.

First lets check the global app parameters which help to configure such shortcuts and also used for localization purposes.

Dialog Shortcuts Parameters

The following global dialog shortcut parameters can be passed on app initialization under dialog property:

var app = new Framework7({
  dialog: {
    // set default title for all dialog shortcuts
    title: 'My App',
    // change default "OK" button text
    buttonOk: 'Done',
    ...
  }
});
ParameterTypeDefaultDescription
titlestringDefault dialogs shortcuts title. If not specified, will be equal to app.name
buttonOkstringOKDefault "OK" button text
buttonCancelstringCancelDefault "Cancel" button text
usernamePlaceholderstringUsernameDefault username field placeholder in Login dialog
passwordPlaceholderstringPasswordDefault password field placeholder in Login & Password dialogs
preloaderTitlestringLoading...Default title for Preloader dialog
progressTitlestringLoading...Default title for Progress dialog
destroyPredefinedDialogsbooleantrueWill automatically destroy all predefined dialogs (Alert, Confirm, Prompt, etc.) on close
keyboardActionsbooleantrueEnables keyboard shortcuts (Enter and Esc) keys for predefined dialogs (Alert, Confirm, Prompt, Login, Password) "Ok" and "Cancel" buttons
autoFocusbooleantrueWhen enabled it autofocus dialog inputs on dialog open. Valid only for predefined dialogs with inputs like Prompt, Login and Password

Now lets look at available dialog shortcuts

Alert

To create Alert dialog we need to use the following app methods:

app.dialog.alert(text, title, callback)- create Alert Dialog and open it

  • text - string. Alert dialog text
  • title - string. Alert dialog title
  • callback - function. Optional. Callback function that will be executed after user clicks on Alert button

Method returns created Dialog's instance

app.dialog.alert(text, callback)- create Alert Dialog with default title and open it

Method returns created Dialog's instance

Confirm

Confirm dialog is usualy used when it is required to confirm some action. To open the Confirm modal we should also call one of the following App methods:

app.dialog.confirm(text, title, callbackOk, callbackCancel)- create Confirm Dialog and open it

  • text - string. Confirm dialog text
  • title - string. Confirm dialog title
  • callbackOk - function. Optional. Callback function that will be executed when user click "Ok" button on Confirm dialog (when user confirms action)
  • callbackCancel - function. Optional. Callback function that will be executed when user click "Cancel" button on Confirm dialog (when user dismisses action)

Method returns created Dialog's instance

app.dialog.confirm(text, callbackOk, callbackCancel)- create Confirm Dialog with default title and open it

Method returns created Dialog's instance

Prompt

Prompt dialog is used when it is required to get some data/answer from user. To open Prompt dialog we should also call one of the following App methods:

app.dialog.prompt(text, title, callbackOk, callbackCancel, defaultValue)- create Prompt Dialog and open it

  • text - string. Prompt dialog text
  • title - string. Prompt dialog title
  • callbackOk - function(value). Optional. Callback function that will be executed when user click "Ok" button on Prompt dialog. As an argument function receives value of text input
  • callbackCancel - function(value). Optional. Callback function that will be executed when user click "Cancel" button on Prompt dialog. As an argument function receives value of text input
  • defaultValue - string. Optional. Prompt input default value

app.dialog.prompt(text, callbackOk, callbackCancel, defaultValue)- create Prompt Dialog with default title and open it

Method returns created Dialog's instance

Login

app.dialog.login(text, title, callbackOk, callbackCancel)- create Login Dialog and open it

  • text - string. Login dialog text
  • title - string. Login dialog title
  • callbackOk - function(username, password). Optional. Callback function that will be executed when user click "Ok" button on Login dialog. As an argument function receives username and password values
  • callbackCancel - function(username, password). Optional. Callback function that will be executed when user click "Cancel" button on Login dialog. As an argument function receives username and password values

app.dialog.login(text, callbackOk, callbackCancel)- create Login Dialog with default title and open it

Method returns created Dialog's instance

Password

Password dialog is useful in case you need to request only the password

app.dialog.password(text, title, callbackOk, callbackCancel)- create Password Dialog and open it

  • text - string. Password dialog text
  • title - string. Password dialog title
  • callbackOk - function(password). Optional. Callback function that will be executed when user click "Ok" button on Password dialog. As an argument function receives password value
  • callbackCancel - function(password). Optional. Callback function that will be executed when user click "Cancel" button on Password dialog. As an argument function receives password value

app.dialog.password(text, callbackOk, callbackCancel)- create Password Dialog with default title and open it

Method returns created Dialog's instance

Preloader

Preloader dialog is used to indicate some background activity (like Ajax request) and to block any user actions during this activity. To open Preloader dialog we should also call appropriate App method:

app.dialog.preloader(title, color)- create Preloader Dialog and open it

  • title - string. Optional. Preloader dialog title
  • color - string. Optional. Preloader color. One of the default colors

Method returns created Dialog's instance

Progress

Same as Preloader dialog but with progressbar instead of preloader.

app.dialog.progress(title, progress, color)- create Progress Dialog and open it

  • title - string. Optional. Progress dialog title
  • progress - number. Optional. Progressbar progress (from 0 to 100). If no number passed then it will have infinite progressbar.
  • color - string. Optional. Progressbar color. One of default colors

Method returns created Dialog's instance

CSS Variables

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

:root {
  --f7-dialog-button-text-color: var(--f7-theme-color);
  --f7-dialog-button-text-align: center;
}
.ios {
  --f7-dialog-width: 270px;
  --f7-dialog-inner-padding: 16px;
  --f7-dialog-border-radius: 13px;
  --f7-dialog-text-align: center;
  --f7-dialog-font-size: 14px;
  --f7-dialog-title-text-color: inherit;
  --f7-dialog-title-font-size: 18px;
  --f7-dialog-title-font-weight: 600;
  --f7-dialog-title-line-height: inherit;
  --f7-dialog-button-font-size: 17px;
  --f7-dialog-button-height: 44px;
  --f7-dialog-button-letter-spacing: 0;
  --f7-dialog-button-font-weight: 400;
  --f7-dialog-button-text-transform: none;
  --f7-dialog-button-strong-bg-color: transparent;
  --f7-dialog-button-strong-text-color: var(--f7-theme-color);
  --f7-dialog-button-strong-font-weight: 500;
  --f7-dialog-input-border-radius: 4px;
  --f7-dialog-input-font-size: 14px;
  --f7-dialog-input-height: 32px;
  --f7-dialog-input-border-width: 1px;
  --f7-dialog-input-placeholder-color: #a9a9a9;
  --f7-dialog-preloader-size: 34px;
  --f7-dialog-input-bg-color: #fff;
  --f7-dialog-bg-color: rgba(255, 255, 255, 0.95);
  --f7-dialog-bg-color-rgb: 255, 255, 255;
  --f7-dialog-text-color: #000;
  --f7-dialog-button-pressed-bg-color: rgba(0, 0, 0, 0.1);
  --f7-dialog-button-strong-pressed-bg-color: rgba(0, 0, 0, 0.1);
  --f7-dialog-input-border-color: rgba(0, 0, 0, 0.3);
  --f7-dialog-border-divider-color: rgba(0, 0, 0, 0.2);
}
.ios .dark,
.ios.dark {
  --f7-dialog-text-color: #fff;
  --f7-dialog-bg-color: rgba(45, 45, 45, 0.95);
  --f7-dialog-bg-color-rgb: 45, 45, 45;
  --f7-dialog-button-pressed-bg-color: rgba(0, 0, 0, 0.2);
  --f7-dialog-button-strong-pressed-bg-color: rgba(0, 0, 0, 0.2);
  --f7-dialog-border-divider-color: rgba(255, 255, 255, 0.15);
  --f7-dialog-input-border-color: rgba(255, 255, 255, 0.15);
  --f7-dialog-input-bg-color: rgba(0, 0, 0, 0.5);
}
.md {
  --f7-dialog-width: 280px;
  --f7-dialog-inner-padding: 24px;
  --f7-dialog-border-radius: 28px;
  --f7-dialog-text-align: left;
  --f7-dialog-font-size: 14px;
  --f7-dialog-title-font-size: 24px;
  --f7-dialog-title-font-weight: 400;
  --f7-dialog-title-line-height: 1.3;
  --f7-dialog-button-font-size: 14px;
  --f7-dialog-button-height: 40px;
  --f7-dialog-button-letter-spacing: normal;
  --f7-dialog-button-font-weight: 500;
  --f7-dialog-button-text-transform: none;
  --f7-dialog-button-strong-font-weight: 500;
  --f7-dialog-input-border-radius: 0px;
  --f7-dialog-input-font-size: 16px;
  --f7-dialog-input-height: 36px;
  --f7-dialog-input-border-color: transparent;
  --f7-dialog-input-border-width: 0px;
  --f7-dialog-preloader-size: 32px;
  --f7-dialog-input-bg-color: transparent;
}
.md,
.md .dark,
.md [class*='color-'] {
  --f7-dialog-button-pressed-bg-color: transparent;
  --f7-dialog-button-strong-bg-color: var(--f7-theme-color);
  --f7-dialog-button-strong-text-color: var(--f7-md-on-primary);
  --f7-dialog-button-strong-pressed-bg-color: transparent;
  --f7-dialog-bg-color: var(--f7-md-surface-3);
  --f7-dialog-input-placeholder-color: var(--f7-md-on-surface-variant);
  --f7-dialog-text-color: var(--f7-md-on-surface-variant);
  --f7-dialog-title-text-color: var(--f7-md-on-surface);
}

Examples

dialog.html
<template>
  <div class="page">
    <div class="navbar">
      <div class="navbar-bg"></div>
      <div class="navbar-inner sliding">
        <div class="title">Dialog</div>
      </div>
    </div>
    <div class="page-content">
      <div class="block block-strong-ios block-outline-ios">
        <p>There are 1:1 replacements of native Alert, Prompt and Confirm modals. They support callbacks, have very easy
          api and can be combined with each other. Check these examples:</p>
        <p class="grid grid-cols-3 grid-gap">
          <button class="button button-fill" @click=${openAlert}>Alert</button>
          <button class="button button-fill" @click=${openConfirm}>Confirm</button>
          <button class="button button-fill" @click=${openPrompt}>Prompt</button>
        </p>
        <p class="grid grid-cols-2 grid-gap">
          <button class="button button-fill" @click=${openLogin}>Login</button>
          <button class="button button-fill" @click=${openPassword}>Password</button>
        </p>
      </div>
      <div class="block-title">Vertical Buttons</div>
      <div class="block block-strong-ios block-outline-ios">
        <p>
          <button class="button button-fill" @click=${openVerticalButtons}>Vertical Buttons</button>
        </p>
      </div>
      <div class="block-title">Preloader Dialog</div>
      <div class="block block-strong-ios block-outline-ios">
        <p class="grid grid-cols-2 grid-gap">
          <button class="button button-fill" @click=${openPreloader}>Preloader</button>
          <button class="button button-fill" @click=${openCustomPreloader}>Custom Text</button>
        </p>
      </div>
      <div class="block-title">Progress Dialog</div>
      <div class="block block-strong-ios block-outline-ios">
        <p class="grid grid-cols-2 grid-gap">
          <button class="button button-fill" @click=${openInfiniteProgress}>Infinite</button>
          <button class="button button-fill" @click=${openDeterminedProgress}>Determined</button>
        </p>
      </div>
      <div class="block-title">Dialogs Stack</div>
      <div class="block block-strong-ios block-outline-ios">
        <p>This feature doesn't allow to open multiple dialogs at the same time, and will automatically open next dialog
          when you close the current one. Such behavior is similar to browser native dialogs: </p>
        <p>
          <button class="button button-fill" @click=${openAlerts}>Open Multiple Alerts</button>
        </p>
      </div>
    </div>
  </div>
</template>
<script>
  export default (props, { $f7 }) => {
    const openAlert = () => {
      $f7.dialog.alert('Hello!');
    }
    const openConfirm = () => {
      $f7.dialog.confirm('Are you feel good today?', function () {
        $f7.dialog.alert('Great!');
      });
    }
    const openPrompt = () => {
      $f7.dialog.prompt('What is your name?', function (name) {
        $f7.dialog.confirm('Are you sure that your name is ' + name + '?', function () {
          $f7.dialog.alert('Ok, your name is ' + name);
        });
      });
    }
    const openLogin = () => {
      $f7.dialog.login('Enter your username and password', function (username, password) {
        $f7.dialog.alert('Thank you!<br />Username:' + username + '<br />Password:' + password);
      });
    }
    const openPassword = () => {
      $f7.dialog.password('Enter your password', function (password) {
        $f7.dialog.alert('Thank you!<br />Password:' + password);
      });
    }
    const openAlerts = () => {
      $f7.dialog.alert('Alert 1');
      $f7.dialog.alert('Alert 2');
      $f7.dialog.alert('Alert 3');
      $f7.dialog.alert('Alert 4');
      $f7.dialog.alert('Alert 5');
    }
    const openVerticalButtons = () => {
      $f7.dialog.create({
        title: 'Vertical Buttons',
        buttons: [
          {
            text: 'Button 1',
          },
          {
            text: 'Button 2',
          },
          {
            text: 'Button 3',
          },
        ],
        verticalButtons: true,
      }).open();
    }
    const openPreloader = () => {
      $f7.dialog.preloader();
      setTimeout(function () {
        $f7.dialog.close();
      }, 3000);
    }
    const openCustomPreloader = () => {
      $f7.dialog.preloader('My text...');
      setTimeout(function () {
        $f7.dialog.close();
      }, 3000);
    }
    const openInfiniteProgress = () => {
      $f7.dialog.progress();
      setTimeout(function () {
        $f7.dialog.close();
      }, 3000);
    }
    const openDeterminedProgress = () => {
      var progress = 0;
      var dialog = $f7.dialog.progress('Loading assets', progress);
      dialog.setText('Image 1 of 10');
      var interval = setInterval(function () {
        progress += 10;
        dialog.setProgress(progress);
        dialog.setText('Image ' + ((progress) / 10) + ' of 10');
        if (progress === 100) {
          clearInterval(interval);
          dialog.close();
        }
      }, 300)
    }

    return $render;
  };
</script>