Initialize App

Now you can see our HTML layout with linked required CSS and JavaScript files. Now we should initialize our app (for example in my-app.js):

var myApp = new Framework7();

In the example above we use myApp variable where we store Framework7 initialized instance for easy access in future. It is not necessary to name it "myApp", it could be any name you like.

It was pretty simple. But Framework7 also provides more customization on initialization by passing object with parameters:

var myApp = new Framework7({
    pushState: true,
    swipePanel: 'left',
    // ... other parameters
});

Let's look at the list of all available parameters:

Parameter Type Default Description
root string 'body' App root element. Useful when using F7 with libraries like Vue or React that doesn't allow to mount the app to the body.
Material Theme (Material theme only)
material boolean false Set to true to activate Material-specific App JS behavior
materialPageLoadDelay number 0 Delay (in ms) before animation of loaded page. Can be increased a bit to improve performance
materialRipple boolean true Enable/disable Material-specific touch ripple effect
materialRippleElements string '.ripple, a.link, a.item-link, .button, .modal-button, .tab-link, .label-radio, .label-checkbox, .actions-modal-button, a.searchbar-clear, .floating-button' CSS selector of elements to apply touch ripple effect on click
materialPreloaderHtml string '<span class="preloader-inner"><span class="preloader-inner-gap"></span><span class="preloader-inner-left"><span class="preloader-inner-half-circle"></span></span><span class="preloader-inner-right"><span class="preloader-inner-half-circle"></span></span></span>' HTML of Material's theme preloader
Caching
cache boolean true As Framework7 uses Ajax to load HTML content for pages it is good to use caching, especially if your content in those pages updates not very often.
cacheDuration number 1000*60*10 Duration in ms (milliseconds) while app will use cache instead of loading page with another Ajax request. By default it takes 10 minutes.
cacheIgnore array [] Array of URLs (string) that should not be cached by Framework7
cacheIgnoreGetParameters boolean false If "true" then URLs like "about.html?id=2" and "about.html?id=3" will be treated and cached like single "about.html" page
Fast clicks library
fastClicks boolean true Fast clicks is a built-in library that removes 300ms delay from links and form elements in mobile browser while you click them. You can disable this built-in library if you want to use other third party fast clicks script.
fastClicksExclude string '' This parameter allows to specify elements not handled by fast clicks by passing CSS selector of such elements
fastClicksDelayBetweenClicks number 50 Minimal allowed delay (in ms) between multiple clicks
fastClicksDistanceThreshold number 10 Distance threshold (in px) to prevent short taps. So if tap/move distance is larger than this value then "click" will not be triggered
activeState boolean true When enabled, app will add "active-state" class to currently touched (:active) element.
activeStateElemets string 'a, button, label, span' CSS selector of elements where activeState will add appropriate active class
tapHold boolean false Set to true to enable tap hold events
tapHoldDelay number 750 Determines how long (in ms) the user must hold their tap before the taphold event is fired on the target element
tapHoldPreventClicks boolean true When enabled (by default), then click event will not be fired after tap hold event
Navigation / Router
router boolean true With this option you may disable default navigation router if you want to implement your own
ajaxLinks string undefined By default (when this parameter is not specified) Framework7 will load all links (<a>) using Ajax. You can change this behavior by passing here CSS selector string for links that should be loaded with Ajax, like "a.ajax" - only all links with "ajax" class
dynamicPageUrl string 'content-{{index}}' URL rule for dynamically loaded pages. Available replaceable expressions: '{{index}}' (page index number in navigation history) and '{{name}}' (value of page "data-page" attribute)
uniqueHistory boolean false Set to true and App will keep View's navigation history unique, and remove duplicated pages
uniqueHistoryIgnoreGetParameters boolean false Use this parameter in addition to uniqueHistory. Set to true and App will ignore URL GET parameters when cheking its uniqueness. So the URLs like "page.html" and "page.html?id=3" will be treated as the same.
externalLinks string '.external' CSS selector for links that should be treated as external and shouldn't be handled by Framework7. For example such '.external' value will match to links like <a href="somepage.html" class="external"> (with class "external")
allowDuplicateUrls boolean false You may enable this parameter to allow loading of new pages that have same url as currently "active" page in View.
animateNavBackIcon boolean false This option (when enabled) gives more native look for dynamic navbar left back-link icon animation. Useful only when you use dynamic navbar with default back-link icon on left side set as "sliding". iOS theme only
animatePages boolean true Set to false if you want to disable animated transitions between pages
preloadPreviousPage boolean true Enable/disable preloading of previous page when you go deep in navigation. Should be enabled for correct work of "swipe back page" feature.
preroute function(view, options) -

This callback allows to prevent default router load/back actions and to load another page or do another required actions

Look for example below

preprocess function(content, url, next) -

This callback function allows you to modify loaded router (mostly Ajax) content right before it will be injected to DOM. Callback receives "content" and "url" of the loaded page and the "next" callback function. After you modify content within this function you should return it with: return content

Look for example below

routerRemoveWithTimeout boolean false

When enabled, then framework will remove element after 0 timeout instead of immediately. Useful to enable if you use another library like Vue or React to manage (remove) pages

Push State
pushState boolean false If you develop web app (not PhoneGap or Home Screen web app) it is useful to enable hash navigation (browser url will look like "http://my-webapp.com/#/about.html"). User as well will be able to navigate through app's history by using browser's default back and forward buttons.
pushStateSeparator string '#!/' Push state URL separator, can be changed for something like '#page/' and then your push state urls will look like "http://myapp.com/#page/about.html"
pushStateRoot string undefined Push state root URL separator, for example "http://my-app.com/". It is useful only in case when you use empty ("") pushStateSeparator
pushStateNoAnimation boolean false If false then it will inherit View's animatePages parameter. If true, then push state navigation will happen without animation (page transitions)
pushStateOnLoad boolean true Disable to ignore parsing push state URL and loading page on app load
Swipe back (iOS theme only)
swipeBackPage boolean true Enable/disable ability to swipe back from left edge of screen to get to the previous page.
swipeBackPageThreshold number 0 Value in px. Swipe back action will start if "touch distance" will be more than this value.
swipeBackPageActiveArea number 30 Value in px. Width of invisible left edge of the screen that triggers swipe back action
swipeBackPageAnimateShadow boolean true Enable/disable box-shadow animation during swipe back action. You can disable it to improve performance
swipeBackPageAnimateOpacity boolean true Enable/disable opacity animation during swipe back action. You can disable it to improve performance
Sortable Lists
sortable boolean true If you don't use sortable lists you can disable it for potentially better performance.
Swipeout
swipeout boolean true If you don't use swipeouts you can disable this feature for potentially better performance.
swipeoutNoFollow boolean false Fallback option for potentially better performance on old/slow devices. If you enable it, then swipeout item will not follow your finger during touch, it will be automatically opened/closed on swipe left/right.
swipeoutRemoveWithTimeout boolean false When enabled, then framework will remove element after 0 timeout instead of immediately. Useful to enable if you use another library like Vue or React to manage (remove) swipeout items
Side Panels
panelLeftBreakpoint number Minimal app width when left panel becomes always visible
panelRightBreakpoint number Minimal app width when right panel becomes always visible
swipePanel string false Disabled by default. If you want to enable ability to open side panels with swipe you can pass here "left" (for left panel) or "right" (for right panel) or "both" (for both panels).
swipePanelCloseOpposite boolean true This parameter gives ability to close opposite panel by swipe. For example, if your swipePanel is "left", then you could close "right" panel also with swipe.
swipePanelOnlyClose boolean false This parameter allows to close (but not open) panels with swipes
swipePanelActiveArea number false Value in px. Width of invisible edge from the screen that triggers swipe panel
swipePanelNoFollow boolean false Fallback option for potentially better performance on old/slow devices. If you enable it, then side panel will not follow your finger during touch, it will be automatically opened/closed on swipe left/right.
swipePanelThreshold number 0 Value in px. Panel will not move with swipe if "touch distance" will be less than this value.
panelsCloseByOutside boolean true Enable/disable ability to close panel by clicking outside of panel (on panel's overlay)
Modals
modalsMoveToRoot boolean true When enabled it will move opened modal to the app root element (or body) if it is not there on the moment of opening and move back after modal closed. It allows to use/load modals on demand inside of loaded pages
modalTitle string 'Framework7' Default title for modals (Alert, Confirm, Prompt)
modalButtonOk string 'OK' Default text for modal's "OK" button
modalButtonCancel string 'Cancel' Default text for modal's "Cancel" button
modalPreloaderTitle string 'Loading... ' Default text for preloader modal
modalCloseByOutside boolean false Enable/disable ability to close modal (Alert, Confirm, Prompt) by clicking outside of modal (on modal's overlay)
actionsCloseByOutside boolean true The same as previous but for Action Sheet modal
popupCloseByOutside boolean true The same as previous but for Popup modal
popoverCloseByOutside boolean true The same as previous but for Popover modal
modalTemplate string undefined Full HTML Template7 formatted HTML template for modals (like alert, confirm and prompt). Look at the example of Modal Template
modalActionsTemplate string undefined Template7 formatted HTML template for Action Sheet. Could be useful if you want to add some custom elements to Action Sheet layout. Look at the example of Action Sheet Template
modalActionsToPopoverTemplate string Template7 formatted HTML template for Action Sheet that will be converted to Popover. Could be useful if you want to add some custom elements to Popover layout. Look at the example of Action Sheet To Popover Template
modalUsernamePlaceholder string 'Username' Place holder text for username input in Login Modal
modalPasswordPlaceholder string 'Password' Place holder text for password input in Login and Password Modals
modalStack boolean true This feature doesn't allow to open multiple modals at the same time, and will automatically open next modal when you close the current one. Such behavior is similar to browser native alerts
Smart Select
smartSelectOpenIn string 'page' Specify default way of how Smart Select should be opened. Can be 'page', 'popup' or 'picker'
smartSelectBackTemplate string '<div class="left sliding"><a href="#" class="back link"><i class="icon icon-back"></i><span>{{backText}}</span></a></div>' Smart Select page navbar back link HTML template
smartSelectPopupCloseTemplate string '<div class="left"><a href="#" class="link close-popup"><i class="icon icon-back"></i><span>{{closeText}}</span></a></div>' Smart Select popup close link HTML template
smartSelectBackText string 'Back' Default back link text for Smart Select's page navbar
smartSelectPopupCloseText string 'Close' Default close link text for Smart Select's popup navbar
smartSelectPickerCloseText string 'Done' Default close link text for Smart Select's picker toolbar
smartSelectSearchbar boolean false Set to true if you want to enable Search Bar for all Smart Selects
smartSelectBackOnSelect boolean false If enabled then smart select page will be automatically closed after user picks any option
smartSelectFormTheme string undefined One of 10 default color themes for form elements on smart select page/popup
smartSelectNavbarTheme string undefined One of 10 default color themes for navbar on smart select page/popup
Navbars / Toolbars
hideNavbarOnPageScroll boolean false Set to true and Navbar will be hidden automatically on page scroll down, and become visible on scroll up
hideToolbarOnPageScroll boolean false Set to true and Toolbar will be hidden automatically on page scroll down, and become visible on scroll up
hideTabbarOnPageScroll boolean false Set to true and Tab bar will be hidden automatically on page scroll down, and become visible on scroll up. Note that this is only for Tab Bar app layout, otherwise use hideToolbarOnPageScroll
showBarsOnPageScrollEnd boolean true Set to true to show hidden Navbar and Toolbar when scrolling reaches end of the page
showBarsOnPageScrollTop boolean true Set to false and bars will not become visible when you scroll page to top everytime. They will become visible only on the most top scroll position, in the beginning of the page
scrollTopOnNavbarClick boolean false Set to true and each click on Navbar's "center" element will scroll currently active page to top
Images Lazy Load
imagesLazyLoadThreshold number 0 By default images are loaded when they appear on the screen. Use this parameter if you want to load images earlier. Setting it to 50 will load image when it 50 pixels before it appears on viewport
imagesLazyLoadSequential boolean true If enabled, then lazy images will be loaded one by one when they appear in viewport
imagesLazyLoadPlaceholder string Lazy load image placeholder source to show while image is not yet loaded. By default it is 1x1 px image
onLazyLoad function (el) Callback function that will be executed when "lazy" image begins to load
onLazyLoaded function (el) Callback function that will be executed when "lazy" image loaded
onLazyError function (el) Callback function that will be executed when "lazy" image fails to load
Notifications
notificationTitle string undefined Default title for all notifications iOS theme only
notificationSubtitle string undefined Default subtitle for all notifications iOS theme only
notificationMedia string undefined Default media (icon or image) for all notifications iOS theme only
notificationHold number undefined Default hold duration (in ms) for all notifications
notificationCloseOnClick boolean false Set to true if you want to close notification on click by default
notificationCloseIcon boolean true Set to true if you want to display close icon (button) for notifications by default iOS theme only
notificationCloseButtonText string 'Close' Default text for Snackbars' close button Material theme only
Status Bar (iOS theme only)
statusbarOverlay boolean undefined With this option you can overwrite automatic status bar detection
scrollTopOnStatusbarClick boolean false Set to true and each click on Status bar ("status-bar-overlay") will scroll currently active page to top
Template7
template7Pages boolean false Set to true to enable Template7 rendering for Ajax and Dynamic pages. Learn more about it in Template7 Pages section
template7Data object {} Parameter to store templates/pages data for Template7 rendering. Learn more about it in Template7 Pages section
precompileTemplates boolean false With this option you may framework will compile all Template7 templates automatically. Learn more about Templates Auto Compilation section
templates object {} Object with compiled Template7 templates. Learn more about it in Templates Auto Compilation section
Page Callbacks
onPageBeforeInit function(app, page) - Callback function that will be executed when Framework7 just inserts new page to DOM. Does the same as "page:beforeinit" page event
onPageInit function(app, page) - Callback function that will be executed when Framework7 initialize required page's components and navbar. Does the same as "page:init" page event
onPageBeforeAnimation function(app, page) - Callback function that will be executed when everything initialized and page (and navbar) is ready to be animated. Does the same as "page:beforeanimation" page event
onPageAfterAnimation function(app, page) - Callback function that will be executed after page (and navbar) animation. Does the same as "page:afteranimation" page event
onPageBeforeRemove function(app, page) - Callback function that will be executed right before page will be removed from DOM. Does the same as "page:beforeremove" page event
onPageBack function(app, page) - Callback function that will be executed right before "back" transition. Difference with "onPageBeforeAnimation" is that this callback will be executed for the "old" page - page that slides from center to right. Does the same as "page:back" page event
onPageAfterBack function(app, page) - Callback function that will be executed right after "back" transition. Difference with "onPageAfterAnimation" is that this callback will be executed for the "old" page - page that slides from center to right. Does the same as "page:afterback" page event
Ajax Callbacks
onAjaxStart function(xhr) - Callback function that will be executed in the beginning of Ajax request. This function accepts xhr data as an argument.
onAjaxComplete function(xhr) - Callback function that will be executed after Ajax request. This function accepts xhr data as an argument.
Namespace

Attention! If you change following class names you will also need to change them in CSS!

viewClass string 'view' Class name for your View element
viewMainClass string 'view-main' Class name for your Main View element
viewsClass string 'views' Class name for your Views element
Init
init boolean true By default Framework7 will be initialized automatically when you call new Framework7(). If you want to prevent this behavior you can disable it with this option and then initialize it manually with myApp.init() when you need it.

So your final initialization code in my-app.js could look like:

var myApp = new Framework7({
    // Default title for modals
    modalTitle: 'My App',
 
    // If it is webapp, we can enable hash navigation:
    pushState: true,
 
    // Hide and show indicator during ajax requests
    onAjaxStart: function (xhr) {
        myApp.showIndicator();
    },
    onAjaxComplete: function (xhr) {
        myApp.hideIndicator();
    }
});   

Example with "preprocess" content

Framework7 allows you to use your favorite client-side template engine or do any modifications with loaded content.

Let's look on how to init app with usage of Template7 as our client-side template engine

Init app in my-app.js:

var myApp = new Framework7({
    preprocess: function (content, url, next) {
        if (url === 'people.html') {
            var template = Template7.compile(content);
            var resultContent = template({
                title: 'People',
                people: ['John', 'Ivan', 'Mary']
            })
            return resultContent;
        }
    }
});

And the people.html page:

<div class="navbar">
  <div class="navbar-inner">
    <div class="center">{{title}}</div>
  </div>
</div>
<div class="pages">
  <div data-page="people" class="page">
    <div class="page-content">
      <ul>
        {{#each people}}
        <li>{{this}}</li>
        {{/each}}
      </ul>
    </div>
  </div>
</div>   

But sometimes you may have asynchronous thread inside of your preprocess functon, for example if you need to do one more Ajax request and only after that to continue page loading. For this case we have "next" callback function where we need to pass our genereated/modified content:

var myApp = new Framework7({
    preprocess: function (content, url, next) {
        if (url === 'people.html') {
            // For example, we will retreive template JSON data using Ajax and only after that we will continue page loading process
            $$.get('sometemplate.html', function(data) {
                // Template
                var template = Template7.compile(content);
 
                // Compile content template with received JSON data
                var resultContent = template(data);
 
                // Now we call "next" callback function with result content
                next(resultContent);
            });
            // Now we shouldn't return anything
        }
    }
});          

Example with "preroute"

This callback allows to prevent default router load/back actions and to load another page, redirects or do another required actions.

For example we can check if the user is not logged in when he requesting some page and then to redirect him to the login page

var myApp = new Framework7({
    preroute: function (view, options) {
        if (!userLoggedIn) {
            view.router.loadPage('auth.html'); //load another page with auth form
            return false; //required to prevent default router action
        }
    }
});

What's next

Ok, right after we initialize our App we need to add and initialize Views