App / Core

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

var app = new Framework7({
  // Enable swipe panel
  panel: {
    swipe: true,
  },
  // ... other parameters
});

This constructor returns main app Framework7 instance.

App Parameters

Lets look at the list of available parameters:

Parameter	Type	Default	Description
el	string	body	App root element. If you main app layout is not a direct child of the `<body>` then it is required to specify root element here
component	Router Component		Load app layout from passed main app component. Only for Framework7 Core version
componentUrl	string Component		Path to Single File main app component to be loaded via XHR. Only for Framework7 Core version
name	string	Framework7	App name. Can be used by other components, e.g. as the default title for Dialog component.
theme	string	auto	App theme. Can be `ios`, `md` or `auto`. In case of `auto` it will use iOS theme for iOS devices and MD theme for all other devices.
colors	object		App colors. Must be an object with mandatory `primary` key and other colors you may need. For all colors specified here, app will generate dynamic CSS styles with Material You color palette. By default it is: `{ primary: '#007aff', red: '#ff3b30', green: '#4cd964', blue: '#2196f3', pink: '#ff2d55', yellow: '#ffcc00', orange: '#ff9500', purple: '#9c27b0', deeppurple: '#673ab7', lightblue: '#5ac8fa', teal: '#009688', lime: '#cddc39', deeporange: '#ff6b22', white: '#ffffff', black: '#000000', }`
userAgent	string		User agent string. Required when used on server-side environments for correct device detection.
routes	array	[]	Array with default routes to all views.
lazyModulesPath	string		Path to Framework7's lazy components. Required to use Lazy Modules with browser modules.
darkMode	boolean string	undefined	If set to `true`, enables dark mode. If set to `false`, disables dark mode. If set to `auto` automatically enables dark theme based on user system color scheme preference. This feature support is based on `(prefers-color-scheme)` media query support.
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 `app.init()` when you need it.
initOnDeviceReady	boolean	true	If automatic initialization is enabled with `init: true` parameter and app is running under cordova environment then it will be initialized on `deviceready` event.
iosTranslucentBars	boolean	true	Enable translucent effect (blur background) on navigation bars for iOS theme (on iOS devices)
iosTranslucentModals	boolean	true	Enable translucent effect (blur background) on modals (Dialog, Popover, Actions) for iOS theme (on iOS devices)
on	object	{}	Object with events handlers. For example: `var app = new Framework7({ on: { init: function () { console.log('App initialized'); }, pageInit: function () { console.log('Page initialized'); }, } })`
Clicks Module Parameters
clicks	object		Object with clicks-module related parameters: `var app = new Framework7({ clicks: { externalLinks: '.external', } })`
{
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")
}
Touch Module Parameters
touch	object		Object with touch-module related parameters: `var app = new Framework7({ touch: { tapHold: true, } })`
{
touchClicksDistanceThreshold	number	5	Distance threshold (in px) to prevent short swipes. So if tap/move distance is larger than this value then "click" will not be triggered.
disableContextMenu	boolean	false	Set to true to disable context menu (with right click or tap and hold)
tapHold	boolean	false	Enables tap hold
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
activeState	boolean	true	When enabled, app will add "active-state" class to currently touched (:active) element.
activeStateElements	string	a, button, label, span, .actions-button, .stepper-button, .stepper-button-plus, .stepper-button-minus, .card-expandable, .menu-item, .link, .item-link, .accordion-item-toggle	CSS selector of elements where enabled `activeState` will add appropriate active class
activeStateOnMouseMove	boolean	false	When enabled it keeps "active state" on mouse move
iosTouchRipple	boolean	false	Enables touch ripple effect for iOS theme
mdTouchRipple	boolean	true	Enables touch ripple effect for MD theme
touchRippleElements	string	.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-content, .list.accordion-list .accordion-item-toggle	CSS selector of elements to apply touch ripple effect on click
touchRippleInsetElements	string	.ripple-inset, .icon-only, .searchbar-disable-button, .input-clear-button, .notification-close-button, .md .navbar .link.back	CSS selector of elements to apply inset touch ripple effect on click
}
serviceWorker	object		Object with service worker module parameters: `var app = new Framework7({ serviceWorker: { path: './service-worker.js', scope: '/', } })`
{
path	string		Path to service worker file
scope	string		Path 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:

var app = new Framework7({
  // Extended by Panel component:
  panel: {
    swipe: true,
    visibleBreakpoint: 1024,
  },
  // Extended by Dialog component:
  dialog: {
    title: 'My App',
  },
  // Extended by Statusbar component:
  statusbar: {
    iosOverlaysWebview: true,
  },
});

App Methods & Properties

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

Properties
app.name	App name passed in parameters
app.routes	App routes
app.el	App root HTML element
app.$el	Dom7 instance with app root HTML element
app.rtl	Boolean property indicating app is in RTL layout or not
app.theme	String with current app theme. Can be `md`, `ios`
app.darkMode	Boolean property that indicates whether the dark theme active or not.
app.width	App width in px
app.height	App height in px
app.left	App left offset in px
app.top	App top offset in px
app.initialized	Boolean property indicating app is initialized or not
app.$	Dom7 alias
app.params	App parameters
app.support	Object with properties about supported features. Check the Support utilities section
app.device	Object with properties about device. Check the Device utilities section
app.utils	Object with some useful utilities. Check the Utils section
app.serviceWorker.container	Service worker container (`navigator.serviceWorker`)
app.serviceWorker.registrations	Array with registered service workers
app.online	Boolean property indication app connection state. (`true` if online)
Methods
app.setColorTheme(color)	Sets primary color theme. `color` must be a HEX color, e.g. `#ff0000`
app.setDarkMode(mode)	If `mode` is `true`, enables dark mode. If `mode` is `false`, disables dark mode. If `mode` is `auto` automatically enables dark theme based on user system color scheme preference.
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:

// Open panel
app.panel.open('left');

// Hide statusbar
app.statusbar.hide();

App Events

App instance emits the following core events:

Event	Arguments	Description
init		Event will be fired on app initialization. Automatically after `new Framework7()` or after `app.init()` if you disabled auto init.
resize		Event will be fired on app resize (window resize).
orientationchange		Event 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
online		Event will be fired when app goes online
offline		Event will be fired when app goes offline
connection	(isOnline)	Event will be fired on network state change
darkModeChange	(isDarkTheme)	Event will be fired on device preferred color scheme change. It has effect only when `darkMode` parameter is set to `'auto'`

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:

app.on('panelOpen', function (panel) {
  console.log('Panel ' + panel.side + ' opened');
});

app.on('connection', function (isOnline) {
  if (isOnline) {
    console.log('app is online now')
  } else {
    console.log('app is offline now')
  }
});

app.on('darkModeChange', function (isDark) {
  if (isDark) {
    console.log('color scheme changed to Dark')
  } else {
    console.log('color scheme changed to Light')
  }
});

CSS Variables

/*====================
  Core
  ==================== */
:root {
  --f7-safe-area-left: 0px;
  --f7-safe-area-right: 0px;
  --f7-safe-area-top: 0px;
  --f7-safe-area-bottom: 0px;

  --f7-safe-area-outer-left: 0px;
  --f7-safe-area-outer-right: 0px;

  @supports (left: env(safe-area-inset-left)) {
    --f7-safe-area-top: env(safe-area-inset-top);
    --f7-safe-area-bottom: env(safe-area-inset-bottom);
    .ios-left-edge,
    .ios-edges,
    .safe-area-left,
    .safe-areas,
    .popup,
    .sheet-modal,
    .panel-left {
      --f7-safe-area-left: env(safe-area-inset-left);
      --f7-safe-area-outer-left: env(safe-area-inset-left);
    }
    .ios-right-edge,
    .ios-edges,
    .safe-area-right,
    .safe-areas,
    .popup,
    .sheet-modal,
    .panel-right {
      --f7-safe-area-right: env(safe-area-inset-right);
      --f7-safe-area-outer-right: env(safe-area-inset-right);
    }
    .no-safe-areas,
    .no-safe-area-left,
    .no-ios-edges,
    .no-ios-left-edge {
      --f7-safe-area-left: 0px;
      --f7-safe-area-outer-left: 0px;
    }
    .no-safe-areas,
    .no-safe-area-right,
    .no-ios-edges,
    .no-ios-right-edge {
      --f7-safe-area-right: 0px;
      --f7-safe-area-outer-right: 0px;
    }
  }

  --f7-device-pixel-ratio: 1;
  @media (min-resolution: 2dppx) {
    --f7-device-pixel-ratio: 2;
  }
  @media (min-resolution: 3dppx) {
    --f7-device-pixel-ratio: 3;
  }
}
/*====================
  Fonts & Bars
  ==================== */
:root {
  --f7-font-size: 14px;

  --f7-bars-translucent-opacity: 0.8;
  --f7-bars-translucent-blur: 20px;
}
.ios {
  --f7-font-family: -apple-system, SF Pro Text, SF UI Text, system-ui, Helvetica Neue, Helvetica, Arial, sans-serif;
  --f7-line-height: 1.4;
  /*
  --f7-bars-link-color: var(--f7-theme-color);
  */
  --f7-bars-text-color: #000;
  --f7-text-color: #000;
  --f7-bars-bg-color: #f7f7f8;
  --f7-bars-bg-color-rgb: 247, 247, 248;
  --f7-bars-border-color: rgba(0,0,0,0.25);
}
.ios .dark,
.ios.dark {
  --f7-bars-text-color: #fff;
  --f7-text-color: #fff;
  --f7-bars-bg-color: #121212;
  --f7-bars-bg-color-rgb: 22, 22, 22;
  --f7-bars-border-color: rgba(255,255,255,0.16);
}

.md {
  --f7-font-family: Roboto, system-ui, Noto, Helvetica, Arial, sans-serif;
  --f7-line-height: 1.5;
  --f7-bars-border-color: transparent;
  --f7-text-color: #212121;
}
.md .dark,
.md.dark {
  --f7-text-color: rgba(255,255,255,0.87);
}

.md,
.md .dark,
.md [class*='color-'] {
  --f7-bars-link-color: var(--f7-md-on-surface);
  --f7-bars-bg-color: var(--f7-md-surface-2);
  --f7-bars-bg-color-rgb: var(--f7-md-surface-2-rgb);
}

/*====================
  Color Themes
  ==================== */
.text-color-primary {
  --f7-theme-color-text-color: var(--f7-theme-color);
}
.bg-color-primary {
  --f7-theme-color-bg-color: var(--f7-theme-color);
}
.border-color-primary {
  --f7-theme-color-border-color: var(--f7-theme-color);
}
.ripple-color-primary {
  --f7-theme-color-ripple-color: rgba(var(--f7-theme-color-rgb), 0.3);
}

Improve this Doc

On this page

App Parameters
App Methods & Properties
App Events
CSS Variables