Framework7 v1
DocsFramework7 VueFramework7 ReactForum

Modal

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

Modals can be opened only using JavaScript. So let's look at related App methods to work with modals

Predefined Modals

  • Note, that if you don't specify predefined modal title, it will use default title ("Framework7") that can be chagend on App initialization by passing modalTitle parameter

  • Buttons text for predefined modals (like "Ok" and "Cancel") can be also chagend on App initialization by passing modalButtonOk and modalButtonCancel parameters

First of all, let's look on most used and already predefined modals in Framework7:

Alert

To open Alert modal we should call one of the following App methods:

myApp.alert(text, [title, callbackOk])
or
myApp.alert(text, [callbackOk])

  • text - string. Text to alert
  • title - string. Optional. Alert modal title
  • callbackOk - function. Optional. Callback function that will be executed when user click "Ok" button on Alert modal
  • This method returns dynamically created modal's HTMLElement
<body>
  ...
  <div class="page-content">
    <div class="content-block">
      <p><a href="#" class="alert-text">Alert With Text</a></p>
      <p><a href="#" class="alert-text-title">Alert With Text and Title</a></p>
      <p><a href="#" class="alert-text-title-callback">Alert With Text and Title and Callback</a></p>
      <p><a href="#" class="alert-text-callback">Alert With Text and Callback</a></p>
    </div>
  </div>
  ...
</body>          
var myApp = new Framework7();
 
var $$ = Dom7;
 
$$('.alert-text').on('click', function () {
    myApp.alert('Here goes alert text');
});
 
$$('.alert-text-title').on('click', function () {
    myApp.alert('Here goes alert text', 'Custom Title!');
});
 
$$('.alert-text-title-callback').on('click', function () {
    myApp.alert('Here goes alert text', 'Custom Title!', function () {
        myApp.alert('Button clicked!')
    });
});
 
$$('.alert-text-callback').on('click', function () {
    myApp.alert('Here goes alert text', function () {
        myApp.alert('Button clicked!')
    });
});

Confirm

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

myApp.confirm(text, [title, callbackOk, callbackCancel])
or
myApp.confirm(text, [callbackOk, callbackCancel])

  • text - string. Confirm text
  • title - string. Optional. Confirm modal title
  • callbackOk - function. Optional. Callback function that will be executed when user click "Ok" button on Confirm modal (when user confirm action)
  • callbackCancel - function. Optional. Callback function that will be executed when user click "Cancel" button on Confirm modal (when user dismiss action)
  • This method returns dynamically created modal's HTMLElement
<body>
  ...
  <div class="page-content">
    <div class="content-block">
      <p><a href="#" class="confirm-ok">Confirm with text and Ok callback</a></p>
      <p><a href="#" class="confirm-ok-cancel">Confirm with text, Ok and Cancel callbacks</a></p>
      <p><a href="#" class="confirm-title-ok">Confirm with text, title and Ok callback</a></p>
      <p><a href="#" class="confirm-title-ok-cancel">Confirm with text, title, Ok and Cancel callback</a></p>
    </div>
  </div>
  ...
</body>            
$$('.confirm-ok').on('click', function () {
    myApp.confirm('Are you sure?', function () {
        myApp.alert('You clicked Ok button');
    });
});
 
$$('.confirm-ok-cancel').on('click', function () {
    myApp.confirm('Are you sure?', 
      function () {
        myApp.alert('You clicked Ok button');
      },
      function () {
        myApp.alert('You clicked Cancel button');
      }
    );
});
$$('.confirm-title-ok').on('click', function () {
    myApp.confirm('Are you sure?', 'Custom Title', function () {
        myApp.alert('You clicked Ok button');
    });
});
$$('.confirm-title-ok-cancel').on('click', function () {
    myApp.confirm('Are you sure?', 'Custom Title', 
      function () {
        myApp.alert('You clicked Ok button');
      },
      function () {
        myApp.alert('You clicked Cancel button');
      }
    );
});

Prompt

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

myApp.prompt(text, [title, callbackOk, callbackCancel])
or
myApp.prompt(text, [callbackOk, callbackCancel])

  • text - string. Prompt text/question
  • title - string. Optional. Prompt modal title
  • callbackOk - function. Optional. Callback function that will be executed when user click "Ok" button on Prompt modal. As an argument function receives value of text input
  • callbackCancel - function. Optional. Callback function that will be executed when user click "Cancel" button on Prompt modal. As an argument function receives value of text input
  • This method returns dynamically created modal's HTMLElement
<body>
  ...
  <div class="page-content">
    <div class="content-block">
      <p><a href="#" class="prompt-ok">Prompt with text and Ok callback</a></p>
      <p><a href="#" class="prompt-ok-cancel">Prompt with text, Ok and Cancel callbacks</a></p>
      <p><a href="#" class="prompt-title-ok">Prompt with text, title and Ok callback</a></p>
      <p><a href="#" class="prompt-title-ok-cancel">Prompt with text, title, Ok and Cancel callback</a></p>
    </div>
  </div>
  ...
</body>  
         
$$('.prompt-ok').on('click', function () {
    myApp.prompt('What is your name?', function (value) {
        myApp.alert('Your name is "' + value + '". You clicked Ok button');
    });
});
 
$$('.prompt-ok-cancel').on('click', function () {
    myApp.prompt('What is your name?', 
      function (value) {
        myApp.alert('Your name is "' + value + '". You clicked Ok button');
      },
      function (value) {
        myApp.alert('Your name is "' + value + '". You clicked Cancel button');
      }
    );
});
$$('.prompt-title-ok').on('click', function () {
    myApp.prompt('What is your name?', 'Custom Title', function (value) {
        myApp.alert('Your name is "' + value + '". You clicked Ok button');
    });
});
$$('.prompt-title-ok-cancel').on('click', function () {
    myApp.prompt('What is your name?', 'Custom Title', 
      function (value) {
        myApp.alert('Your name is "' + value + '". You clicked Ok button');
      },
      function (value) {
        myApp.alert('Your name is "' + value + '". You clicked Cancel button');
      }
    );
});

Login and Password

There are also two special modals for authentication:

myApp.modalLogin(text, [title, callbackOk, callbackCancel])
or
myApp.modalLogin(text, [callbackOk, callbackCancel])

  • text - string. Modal text
  • title - string. Optional. Modal title
  • callbackOk - function. Optional. Callback function that will be executed when user click "Ok" button. As an argument function receives username and password values
  • callbackCancel - function. Optional. Callback function that will be executed when user click "Cancel" button. As an argument function receives username and password values
  • This method returns dynamically created modal's HTMLElement

myApp.modalPassword(text, [title, callbackOk, callbackCancel])
or
myApp.modalPassword(text, [callbackOk, callbackCancel])

  • text - string. Modal text
  • title - string. Optional. Modal title
  • callbackOk - function. Optional. Callback function that will be executed when user click "Ok" button. As an argument function receives password value
  • callbackCancel - function. Optional. Callback function that will be executed when user click "Cancel" button. As an argument function receives password value
<div class="page-content">
  <div class="content-block">
    <p><a href="#" class="login-modal">Login Modal</a></p>
    <p><a href="#" class="password-modal">Password Modal</a></p>
  </div>
</div>  
var myApp = new Framework7();
 
var $$ = Dom7;
 
$$('.login-modal').on('click', function () {
    myApp.modalLogin('Authentication required', function (username, password) {
        myApp.alert('Thank you! Username: ' + username + ', Password: ' + password);
    });
});
 
$$('.password-modal').on('click', function () {
    myApp.modalPassword('You password please:', function (password) {
        myApp.alert('Thank you! Your password is: ' + password);
    });
});

Nesting Modals

And of course as you may already note, you can "nest" this modals in each other callbacks:

<body>
  ...
  <div class="page-content">
    <div class="content-block">
      <p><a href="#" class="name">What is your name?</a></p>
    </div>
  </div>
  ...
</body> 
$$('.name').on('click', function () {
    myApp.prompt('What is your name?', function (value) {
        myApp.confirm('Are you sure that your name is ' + value + '?', function () {
            myApp.alert('Ok, your name is "' + value + '"!');
        });
    });
});

Preloader Modal

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

myApp.showPreloader([title]) - show modal with Preloader

  • title - string. Optional. Preloader modal title. By default (if not specified) it is euqal to "Loading...". You can change default Preloader title by passing modalPreloaderTitle parameter on App initialization
  • This method returns dynamically created modal's HTMLElement

myApp.hidePreloader() - hide/close modal with Preloader. Because Preloader modal has not any buttons, it should be closed by JavaScript

<body>
  ...
  <div class="page-content">
    <div class="content-block">
      <p><a href="#" class="open-preloader">Open Preloader</a></p>
      <p><a href="#" class="open-preloader-title">Open Preloader with custom title</a></p>
    </div>
  </div>
  ...
</body>          
$$('.open-preloader').on('click', function () {
    myApp.showPreloader();
    setTimeout(function () {
        myApp.hidePreloader();
    }, 2000);
});
$$('.open-preloader-title').on('click', function () {
    myApp.showPreloader('Custom Title')
    setTimeout(function () {
        myApp.hidePreloader();
    }, 2000);
});

Indicator

If you don't need such "big" modal window like Preloader Modal to indicate activity, you can use simple and small indicator modal:

myApp.showIndicator() - show modal with Indicator

myApp.hideIndicator() - hide/close modal with Indicator. Because Indicator modal has not any buttons, it should be closed by JavaScript

<body>
  ...
  <div class="page-content">
    <div class="content-block">
      <p><a href="#" class="open-indicator">Open Indicator</a></p>
    </div>
  </div>
  ...
</body>          
$$('.open-indicator').on('click', function () {
    myApp.showIndicator();
    setTimeout(function () {
        myApp.hideIndicator();
    }, 2000);
});

Custom Modals

Ok, all predefined modals were just particular case (like shortcuts) of full Modal methods. Let's look how to create custom modals:

myApp.modal(parameters) - show custom modal

  • parameters - object. Object with Modal parameters/options
  • This method returns dynamically created modal's HTMLElement

Here is the list of Modal parameters:

Parameter Type Default Description
title string Optional. String with Modal title (could be HTML string)
text string Optional. String with Modal text (could be HTML string)
afterText string Optional. String with text (could be HTML string) that will be placed after "text"
buttons array Optional. Array of buttons. Each button should be presented as Object with button parameters (look below)
verticalButtons boolean false Optional. Set to true to enable vertical buttons layout
onClick function Optional. Callback function that will be executed when user clicks any of Modal's button. As arguments it receives modal (with Modal's HTMLElement) and index (with index number of clicked button)

Let's look at Button's 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
close boolean true Optional. If "true" then modal will be closed after click on this button
onClick function Optional. Callback function that will be executed when user click this button

Such configuration options allows to create flexible modals. Let's look at some examples.

<body>
  ...
  <div class="page-content">
    <div class="content-block">
      <p><a href="#" class="open-3-modal">Modal With 3 Buttons</a></p>
      <p><a href="#" class="open-slider-modal">Modal With Slider</a></p>
      <p><a href="#" class="open-tabs-modal">Modal With Tabs</a></p>
      <p><a href="#" class="open-vertical-modal">Modal With Vertical Buttons</a></p>
    </div>
  </div>
  ...
</body>  
$$('.open-3-modal').on('click', function () {
  myApp.modal({
    title:  'Modal with 3 buttons',
    text: 'Vivamus feugiat diam velit. Maecenas aliquet egestas lacus, eget pretium massa mattis non. Donec volutpat euismod nisl in posuere. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae',
    buttons: [
      {
        text: 'B1',
        onClick: function() {
          myApp.alert('You clicked first button!')
        }
      },
      {
        text: 'B2',
        onClick: function() {
          myApp.alert('You clicked second button!')
        }
      },
      {
        text: 'B3',
        bold: true,
        onClick: function() {
          myApp.alert('You clicked third button!')
        }
      },
    ]
  })
});
$$('.open-slider-modal').on('click', function () {
  var modal = myApp.modal({
    title: 'Awesome Photos?',
    text: 'What do you think about my photos?',
    afterText:  '<div class="swiper-container" style="width: auto; margin:5px -15px -15px">'+
                  '<div class="swiper-pagination"></div>'+
                  '<div class="swiper-wrapper">'+
                    '<div class="swiper-slide"><img src="..." height="150" style="display:block"></div>' +
                    '<div class="swiper-slide"><img src="..." height="150" style="display:block"></div>'+
                  '</div>'+
                '</div>',
    buttons: [
      {
        text: 'Bad :('
      },
      {
        text: 'Awesome!',
        bold: true,
        onClick: function () {
          myApp.alert('Thanks! I know you like it!')
        }
      },
    ]
  })
  myApp.swiper($$(modal).find('.swiper-container'), {pagination: '.swiper-pagination'});
});
 
$$('.open-tabs-modal').on('click', function () {
  myApp.modal({
    title:  '<div class="buttons-row">'+
              '<a href="#tab1" class="button active tab-link">Tab 1</a>'+
              '<a href="#tab2" class="button tab-link">Tab 2</a>'+
            '</div>',
    text: '<div class="tabs">'+
            '<div class="tab active" id="tab1">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam convallis nunc non dolor euismod feugiat. Sed at sapien nisl. Ut et tincidunt metus. Suspendisse nec risus vel sapien placerat tincidunt. Nunc pulvinar urna tortor.</div>'+
            '<div class="tab" id="tab2">Vivamus feugiat diam velit. Maecenas aliquet egestas lacus, eget pretium massa mattis non. Donec volutpat euismod nisl in posuere. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae</div>'+
          '</div>',
    buttons: [
      {
        text: 'Ok, got it',
        bold: true
      },
    ]
  })
});
 
$$('.open-vertical-modal').on('click', function () {
  myApp.modal({
    title:  'Vertical Buttons Layout',
    text: 'Vivamus feugiat diam velit. Maecenas aliquet egestas lacus, eget pretium massa mattis non. Donec volutpat euismod nisl in posuere. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae',
    verticalButtons: true,
    buttons: [
      {
        text: 'Button 1',
        onClick: function() {
          myApp.alert('You clicked first button!')
        }
      },
      {
        text: 'Button 2',
        onClick: function() {
          myApp.alert('You clicked second button!')
        }
      },
      {
        text: 'Button 3',
        onClick: function() {
          myApp.alert('You clicked third button!')
        }
      },
    ]
  })
});

Close Modals With JavaScript

Any Modal can be closed with JavaScript, not only by clicking on its buttons. For this we need to look at relate App method:

myApp.closeModal(modal) - close any modal

  • modal - HTMLElement or string (with CSS Selector). Optional. If not specified, any opened modal will be closed

Modal Events

Modal events could be very useful when you need to do something in JavaScript when Modal opened/closed

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

Modal Template

If you want to customize Modal template, you may customize it by passing modalTemplate 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:

<div class="modal {{#unless buttons}}modal-no-buttons{{/unless}}">
  <div class="modal-inner">
    {{#if title}}
      <div class="modal-title">{{title}}</div>
    {{/if}}
    {{#if text}}
       <div class="modal-text">{{text}}</div>
    {{/if}}
    {{#if afterText}}
      {{afterText}}
    {{/if}}
  </div>
  {{#if buttons}}
    <div class="modal-buttons">
      {{#each buttons}}
        <span class="modal-button {{#if bold}}modal-button-bold{{/if}}">{{text}}</span>
      {{/each}}
    </div>
  {{/if}}
</div>