App / Core

When we init the app we can use the new Framework7 constructor and pass an object with main app parameters:

  1. var app = new Framework7({
  2.   // App id
  3.   id: 'com.myapp.test',
  4.   // Enable swipe panel
  5.   panel: {
  6.     swipe: 'left',
  7.   },
  8.   // ... other parameters
  9. });

This constructor returns main app Framework7 instance.

App Parameters

Lets look at the list of available parameters:

ParameterTypeDefaultDescription
rootstringbodyApp root element. If you main app layout is not a direct child of the <body> then it is required to specify root element here
componentRouter ComponentLoad app layout from passed main app component. Only for Framework7 Core version
componentUrlstring ComponentPath to Single File main app component to be loaded via XHR. Only for Framework7 Core version
idstringio.framework7.testappApp bundle id.
namestringFramework7App name. Can be used by other components, e.g. as the default title for Dialog component.
versionstring1.0.0App version. Can be used by other components.
themestringautoApp theme. Can be ios, md, aurora or auto. In case of auto it will use iOS theme for iOS devices, Aurora theme for desktop device running in Electron environment, and MD theme for all other devices.
languagestringApp language. Can be used by other components. By default equal to the current browser/webview language (i.e. navigator.language).
routesarray[]Array with default routes to all views.
datafunctionApp root data. Must be a function that returns an object with root data. For example:
  1. var app = new Framework7({
  2.   data: function () {
  3.     return {
  4.       username: ‘vladimir’,
  5.       firstName: ‘Vladimir’,
  6.       lastName: ‘Kharlampidi’
  7.     };
  8.   },
  9. });

Note, that this inside of this data function points to app Framework7 instance.

methodsobject{}App root methods. Object with methods, e.g.
  1. var app = new Framework7({
  2.   methods: {
  3.     alert: function() {
  4.       app.dialog.alert(‘Hello World’);
  5.     }
  6.   }
  7. });

Note, that this inside of each method points to app Framework7 instance.

lazyModulesPathstringPath to Framework7’s lazy components. Required to use Lazy Modules with browser modules.
autoDarkThemebooleanfalseAutomatically enables dark theme based on user system color scheme preference. This feature support is based on (prefers-color-scheme) media query support.
initbooleantrueBy 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 app.init() when you need it.
initOnDeviceReadybooleantrueIf automatic initialization is enabled with init: true parameter and app is running under cordova environment then it will be initialized on deviceready event.
iosTranslucentBarsbooleantrueEnable translucent effect (blur background) on navigation bars for iOS theme (on iOS devices)
iosTranslucentModalsbooleantrueEnable translucent effect (blur background) on modals (Dialog, Popover, Actions) for iOS theme (on iOS devices)
onobject{}

Object with events handlers. For example:

  1. var app = new Framework7({
  2.   on: {
  3.     init: function () {
  4.       console.log(‘App initialized’);
  5.     },
  6.     pageInit: function () {
  7.       console.log(‘Page initialized’);
  8.     },
  9.   }
  10. })
Clicks Module Parameters
clicksobjectObject with clicks-module related parameters:
  1. var app = new Framework7({
  2.   clicks: {
  3.     externalLinks: ‘.external’,
  4.   }
  5. })
{
externalLinksstring‘.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”)
}
Touch Module Parameters
touchobjectObject with touch-module related parameters:
  1. var app = new Framework7({
  2.   touch: {
  3.     tapHold: true,
  4.   }
  5. })
{
touchClicksDistanceThresholdnumber5Distance threshold (in px) to prevent short swipes. So if tap/move distance is larger than this value then “click” will not be triggered. (Used only for touch events when fastClicks disabled).
disableContextMenubooleanfalseSet to true to disable context menu (with right click or tap and hold)
tapHoldbooleanfalseEnables tap hold
tapHoldDelaynumber750Determines how long (in ms) the user must hold their tap before the taphold event is fired on the target element
tapHoldPreventClicksbooleantrueWhen enabled (by default), then click event will not be fired after tap hold event
activeStatebooleantrueWhen enabled, app will add “active-state” class to currently touched (:active) element.
activeStateElementsstringa, button, label, span, .actions-button, .stepper-button, .stepper-button-plus, .stepper-button-minus, .card-expandable, .menu-item, .link, .item-linkCSS selector of elements where enabled activeState will add appropriate active class
activeStateOnMouseMovebooleanfalseWhen enabled it keeps “active state” on mouse move
iosTouchRipplebooleanfalseEnables touch ripple effect for iOS theme
mdTouchRipplebooleantrueEnables touch ripple effect for MD theme
auroraTouchRipplebooleanfalseEnables touch ripple effect for Aurora theme
touchRippleElementsstring.ripple, .link, .item-link, .list-button, .links-list a, .button, button, .input-clear-button, .dialog-button, .tab-link, .item-radio, .item-checkbox, .actions-button, .searchbar-disable-button, .fab a, .checkbox, .radio, .data-table .sortable-cell:not(.input-cell), .notification-close-button, .stepper-button, .stepper-button-minus, .stepper-button-plus, .menu-item-contentCSS selector of elements to apply touch ripple effect on click
}
serviceWorkerobjectObject with service worker module parameters:
  1. var app = new Framework7({
  2.   serviceWorker: {
  3.     path: ‘./service-worker.js’,
  4.     scope: ‘/‘,
  5.   }
  6. })
{
pathstringPath to service worker file
scopestringPath to service worker scope
}

These are default app parameters for app core module.

Most of components that has JavaScript API may extend this list of parameters with the property named as component. For example Panel component extends app parameters with panel property that accepts Panel specific parameters.

Example:

  1. var app = new Framework7({
  2.   id: 'com.myapp.test',
  3.   // Extended by Panel component:
  4.   panel: {
  5.     swipe: 'left',
  6.     leftBreakpoint: 768,
  7.     rightBreakpoint: 1024,
  8.   },
  9.   // Extended by Dialog component:
  10.   dialog: {
  11.     title: 'My App',
  12.   },
  13.   // Extended by Statusbar component:
  14.   statusbar: {
  15.     iosOverlaysWebview: true,
  16.   },
  17. });

App Methods & Properties

Returned Framework7 instance app contains a lot of useful properties and methods:

Properties
app.idApp ID passed in parameters
app.nameApp name passed in parameters
app.versionApp version
app.routesApp routes
app.languageApp language
app.rootDom7 instance with app root element
app.rootComponentReference to main app component instance (if it is used). Only for Framework7 Core version
app.rtlBoolean property indicating app is in RTL layout or not
app.themeString with current app theme. Can be md, ios or aurora
app.darkThemeBoolean property that indicates whether the dark theme active or not. This property has effect only when autoDarkTheme enabled.
app.dataObject with app root data passed on intialization
app.methodsObject with app root methods
app.widthApp width in px
app.heightApp height in px
app.leftApp left offset in px
app.topApp top offset in px
app.initializedBoolean property indicating app is initialized or not
app.$Dom7 alias
app.t7Template7 alias
app.paramsApp parameters
app.supportObject with properties about supported features. Check the Support utilities section
app.deviceObject with properties about device. Check the Device utilities section
app.utilsObject with some useful utilities. Check the Utils section
app.requestContains methods to work with XHR requests. Check the Request utilities section
app.serviceWorker.registrationArray with registered service workers
app.onlineBoolean property indication app conntection state. (true if online)
Methods
app.enableAutoDarkTheme()Enables auto dark theme detection
app.disableAutoDarkTheme()Disables auto dark theme detection
app.on(event, handler)Add event handler
app.once(event, handler)Add event handler that will be removed after it was fired
app.off(event, handler)Remove event handler
app.off(event)Remove all handlers for specified event
app.emit(event, …args)Fire event on instance
app.init()Initialize app. In case you disabled auto initialization with init: false parameter
app.serviceWorker.register(path, scope)Register service worker. It returns promise that will be resolved with ServiceWorkerRegistration
app.serviceWorker.unregister(registration)Unregister service worker. It returns promise that will be resolved when service worker unregistered.

Same as with app parameters most of components that has JavaScript API may extend this list of properties with the property named as component. For example Panel component extends app instance properties with panel property that accepts Panel specific properties and methods.

Example:

  1. // Open panel
  2. app.panel.open('left');
  4. // Hide statusbar
  5. app.statusbar.hide();

App Events

App instance emits the following core events:

EventArgumentsDescription
initEvent will be fired on app initialization. Automatically after new Framework7() or after app.init() if you disabled auto init.
resizeEvent will be fired on app resize (window resize).
orientationchangeEvent will be fired on app orientation change (window orientantion change).
click(event)Event will be fired on app click
touchstart:active(event)Event will be fired on touch start (mousedown) event added as active listener (possible to prevent default)
touchmove:active(event)Event will be fired on touch move (mousemove) event added as active listener (possible to prevent default)
touchend:active(event)Event will be fired on touch end (mouseup) event added as active listener (possible to prevent default)
touchstart:passive(event)Event will be fired on touch start (mousedown) event added as passive listener (impossible to prevent default)
touchmove:passive(event)Event will be fired on touch move (mousemove) event added as passive listener (impossible to prevent default)
touchend:passive(event)Event will be fired on touch end (mouseup) event added as passive listener (impossible to prevent default)
serviceWorkerRegisterSuccess(registration)Event will be triggered when service worker successfully registered
serviceWorkerRegisterError(error)Event will be triggered when service worker registration failed
serviceWorkerUnregisterSuccess(registration)Event will be triggered when service worker successfully unregistered
serviceWorkerUnregisterError(registration, error)Event will be triggered when service worker unregister failed
onlineEvent will be fired when app goes online
offlineEvent will be fired when app goes offline
connection(isOnline)Event will be fired on network state change
darkThemeChange(isDarkTheme)Event will be fired on device preferred color scheme change. It has effect only when autoDarkTheme enabled

And again, most of components that has JavaScript API may extend this list of events like Panel component will also trigger additional events on app instance.

Examples:

  1. app.on('panelOpen', function (panel) {
  2.   console.log('Panel ' + panel.side + ' opened');
  3. });
  5. app.on('connection', function (isOnline) {
  6.   if (isOnline) {
  7.     console.log('app is online now')
  8.   } else {
  9.     console.log('app is offline now')
  10.   }
  11. });
  13. app.on('darkThemeChange', function (isDark) {
  14.   if (isDark) {
  15.     console.log('color scheme changed to Dark')
  16.   } else {
  17.     console.log('color scheme changed to Light')
  18.   }
  19. });

CSS Variables

  1. :root {
  2.   --f7-theme-color: #007aff;
  3.   --f7-theme-color-rgb: 0, 122, 255;
  4.   --f7-theme-color-shade: #0066d6;
  5.   --f7-theme-color-tint: #298fff;
  6.   --f7-safe-area-left: 0px;
  7.   --f7-safe-area-right: 0px;
  8.   --f7-safe-area-top: 0px;
  9.   --f7-safe-area-bottom: 0px;
  10.   --f7-safe-area-outer-left: 0px;
  11.   --f7-safe-area-outer-right: 0px;
  12.   --f7-device-pixel-ratio: 1;
  13. }
  14. @supports (left: env(safe-area-inset-left)) {
  15.   :root {
  16.     --f7-safe-area-top: env(safe-area-inset-top);
  17.     --f7-safe-area-bottom: env(safe-area-inset-bottom);
  18.   }
  19.   :root .ios-left-edge,
  20.   :root .ios-edges,
  21.   :root .safe-area-left,
  22.   :root .safe-areas,
  23.   :root .popup,
  24.   :root .sheet-modal,
  25.   :root .panel-left {
  26.     --f7-safe-area-left: env(safe-area-inset-left);
  27.     --f7-safe-area-outer-left: env(safe-area-inset-left);
  28.   }
  29.   :root .ios-right-edge,
  30.   :root .ios-edges,
  31.   :root .safe-area-right,
  32.   :root .safe-areas,
  33.   :root .popup,
  34.   :root .sheet-modal,
  35.   :root .panel-right {
  36.     --f7-safe-area-right: env(safe-area-inset-right);
  37.     --f7-safe-area-outer-right: env(safe-area-inset-right);
  38.   }
  39.   :root .no-safe-areas,
  40.   :root .no-safe-area-left,
  41.   :root .no-ios-edges,
  42.   :root .no-ios-left-edge {
  43.     --f7-safe-area-left: 0px;
  44.     --f7-safe-area-outer-left: 0px;
  45.   }
  46.   :root .no-safe-areas,
  47.   :root .no-safe-area-right,
  48.   :root .no-ios-edges,
  49.   :root .no-ios-right-edge {
  50.     --f7-safe-area-right: 0px;
  51.     --f7-safe-area-outer-right: 0px;
  52.   }
  53. }
  54. @media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 2dppx) {
  55.   :root {
  56.     --f7-device-pixel-ratio: 2;
  57.   }
  58. }
  59. @media (-webkit-min-device-pixel-ratio: 3), (min-resolution: 3dppx) {
  60.   :root {
  61.     --f7-device-pixel-ratio: 3;
  62.   }
  63. }
  64. /*====================
  65.   Fonts & Bars
  66.   ==================== */
  67. :root {
  68.   --f7-font-size: 14px;
  69.   /*
  70.   --f7-bars-link-color: var(--f7-theme-color);
  71.   */
  72.   --f7-bars-bg-image: none;
  73.   --f7-bars-translucent-opacity: 0.8;
  74.   --f7-bars-translucent-blur: 20px;
  75.   --f7-bars-shadow-bottom-image: linear-gradient(to bottom, rgba(0, 0, 0, 0.25) 0%, rgba(0, 0, 0, 0.08) 40%, rgba(0, 0, 0, 0.04) 50%, rgba(0, 0, 0, 0) 90%, rgba(0, 0, 0, 0) 100%);
  76.   --f7-bars-shadow-top-image: linear-gradient(to top, rgba(0, 0, 0, 0.25) 0%, rgba(0, 0, 0, 0.08) 40%, rgba(0, 0, 0, 0.04) 50%, rgba(0, 0, 0, 0) 90%, rgba(0, 0, 0, 0) 100%);
  77.   --f7-bars-text-color: #000;
  78.   --f7-bars-bg-color: #f7f7f8;
  79.   --f7-bars-bg-color-rgb: 247, 247, 248;
  80. }
  81. :root .theme-dark,
  82. :root.theme-dark {
  83.   --f7-bars-text-color: #fff;
  84. }
  85. .ios {
  86.   --f7-font-family: -apple-system, SF Pro Text, SF UI Text, system-ui, Helvetica Neue, Helvetica, Arial, sans-serif;
  87.   --f7-line-height: 1.4;
  88.   --f7-text-color: #000;
  89.   --f7-bars-border-color: rgba(0, 0, 0, 0.25);
  90. }
  91. .ios .theme-dark,
  92. .ios.theme-dark {
  93.   --f7-text-color: #fff;
  94.   --f7-bars-bg-color: #121212;
  95.   --f7-bars-bg-color-rgb: 19, 19, 19;
  96.   --f7-bars-border-color: rgba(255, 255, 255, 0.1);
  97. }
  98. .md {
  99.   --f7-font-family: Roboto, system-ui, Noto, Helvetica, Arial, sans-serif;
  100.   --f7-line-height: 1.5;
  101.   --f7-bars-border-color: transparent;
  102.   --f7-text-color: #212121;
  103. }
  104. .md .theme-dark,
  105. .md.theme-dark {
  106.   --f7-text-color: rgba(255, 255, 255, 0.87);
  107.   --f7-bars-bg-color: #202020;
  108. }
  109. .aurora {
  110.   --f7-font-family: -apple-system, system-ui, Helvetica, Arial, sans-serif;
  111.   --f7-line-height: 1.5;
  112.   --f7-text-color: #000;
  113.   --f7-bars-border-color: rgba(0, 0, 0, 0.2);
  114. }
  115. .aurora .theme-dark,
  116. .aurora.theme-dark {
  117.   --f7-text-color: #fff;
  118.   --f7-bars-bg-color: #202020;
  119.   --f7-bars-border-color: rgba(255, 255, 255, 0.1);
  120. }

← Router Component

Accordion / Collapsible →