Popup
Basic usage
The popup provides a frame for all your pop-over needs, able to render custom content, forms or combined views.
Use it for contextual pop-ups, data-entry or to inform users in a consistent way with all other Mobiscroll component.
var instance = mobiscroll.popup('#mypopup');
document
.getElementById('show')
.addEventListener('click', function () {
instance.open();
}, false);
<div id="mypopup">
<h3>Hi</h3>
<p>Are you feeling good today?</p>
</div>
<button id="show">Open popup</button>
Passing options
Options can be passed as an object for the initialization function.
var instance = mobiscroll.popup('#mypopup', {
theme: 'ios',
buttons: ['ok', 'cancel']
});
Changing options
After initialization the options can be changed any time by using the setOptions method.
instance.setOptions({
theme: 'material',
buttons: ['close']
});
For many more examples - simple and complex use-cases - check out the popup demos for javascript.
Typescript Types
When using with typescript, the following types are available for the Popup:
Type | Description |
---|---|
Popup | Type of the Popup instance |
MbscPopupOptions | Type of the settings object that is used to initialize the component |
Options
Name | Type | Default value | Description |
---|---|---|---|
anchor | HTMLElement | undefined |
Specifies the anchor element for positioning, if display is set to
'anchored'
.
If undefined, it defaults to the element on which the component was initialized.
|
animation | String, Boolean | undefined |
Animation to use for opening/closing of the control (if display is not inline). Possible values:
false , turns the animation off.
|
buttons | Array |
['ok']
|
Buttons to display. Each item in the array will be a button. A button can be specified as a string, or as a button object.
If a string, it must be one of the predefined buttons:
If an object, it may have the following properties:
Predefined and custom buttons example
Predefined button handler example
|
closeOnEsc | Boolean | true |
If true, the popup is closed on ESC keypress. |
closeOnOverlayClick | Boolean | true |
If true, the popup is closed on overlay tap/click. |
context | String, HTMLElement | 'body' |
The DOM element in which the component is appended and positioned (if not inline). Can be a selector string or a DOM element. |
cssClass | String | undefined |
Applies custom css class to the top level element.
The
mbsc-no-padding class removes the padding around another component inside the popup. |
disabled | Boolean | false |
Initial disabled state of the component. This will take no effect in inline display mode. |
display | String | undefined |
Controls the positioning of the component. Possible options:
The default display mode depends on the theme,
it defaults to |
focusOnClose | Boolean, String, HTMLElement |
true
|
Element to focus after the popup is closed.
If undefined , the original element will be focused.
If false , no focusing will occur.
|
focusTrap | Boolean | true |
If not in inline mode, focus won't be allowed to leave the popup. |
fullScreen | Boolean | false |
If true , the popup will appear in full screen, but, by default, its width and height won't exceed 600px.
You can change that using the maxWidth and maxHeight options.
|
headerText | String | undefined |
Text to display in the header. |
height | Number, String | undefined |
Sets the height of the component. |
maxHeight | Number, String | undefined |
Sets the maximum height of the component. If not specified, on larger screens (>=768px width) it defaults to 600px. |
maxWidth | Number, String | 600 |
Sets the maximum width of the component. |
responsive | Object | undefined |
Specify different settings for different container widths, in a form of an object,
where the keys are the name of the breakpoints, and the values are objects containing
the settings for the given breakpoint.
The available width is queried from the container element of the component and not the browsers viewport like in css media queries
There are five predefined breakpoints:
breakpoint
property specifying the min-width in pixels.
Example:
|
scrollLock | Boolean | true |
Disables page scrolling on touchmove (if not in inline mode, and popup height is less than window height). |
showArrow | Boolean | true |
Show or hide the popup arrow, when display mode is 'anchored' .
|
showOverlay | Boolean | true |
Show or hide overlay. |
theme | String | undefined |
Sets the visual appearance of the component.
If it is
Make sure that the theme you set is included in the downloaded package.
|
themeVariant | String | undefined |
Controls which variant of the theme will be used (light or dark). Possible values:
To use the option with custom themes, make sure to create two custom themes,
where the dark version has the same name as the light one, suffixed with |
touchUi | Boolean, String | 'auto' |
Use Can be used with the responsive option to change the user interface based on viewport width.
If set to |
width | Number, String | undefined |
Sets the width of the popup container. This will take no effect in inline display mode. |
Setting options dynamically
To change one or more options on the component after initialization, use the setOptions method. This will update the component without losing it's internal state.
var inst = mobiscroll.popup({
theme: 'ios'
});
// Changes the theme to Material
inst.setOptions({ theme: 'material' });
Events
Name | Description | |
---|---|---|
onClose(event, inst) |
Triggered when the component is closed.
Parameters
Example
|
|
onDestroy(event, inst) |
Triggered when the component is destroyed.
Parameters
Example
|
|
onInit(event, inst) |
Triggered when the component is initialized.
Parameters
Example
|
|
onOpen(event, inst) |
Triggered when the component is opened.
Parameters
Example
|
|
onPosition(event, inst) |
Triggered when the component is positioned (on initial show and resize / orientation change).
Useful if dimensions needs to be modified before the positioning happens, e.g. set a custom width or height. Custom positioning can also be implemented here, in this case, returning false from the handler
function will prevent the built in positioning.
Parameters
Example
|
Methods
Name | Description | |
---|---|---|
close() |
Closes the component.
ExampleMethods can be called on an instance. For more details see calling methods
|
|
getInst() |
Returns the object instance.
Returns: Object
ExampleMethods can be called on an instance. For more details see calling methods
|
|
isVisible() |
Returns a boolean indicating whether the component is visible or not.
Returns: Boolean
ExampleMethods can be called on an instance. For more details see calling methods
|
|
open() |
Opens the component.
ExampleMethods can be called on an instance. For more details see calling methods
|
|
position() |
Recalculates the position of the component (if not inline).
ExampleMethods can be called on an instance. For more details see calling methods
|
|
setOptions(options) |
Update options for the component.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
Localization
Name | Type | Default value | Description |
---|---|---|---|
cancelText | String | 'Cancel' |
Text for Cancel button. |
closeText | String | 'Close' |
Text for the close button. |
locale | Object | undefined |
Sets the language of the component.
The locale option is an object containing all the translations for a given language.
Mobiscroll supports a number of languages listed below. If a language is missing from the list, it can also be provided by the user. Here's a guide on
how to write language modules.
Supported languages:
In some cases it's more convenient to set the locale using the language code string.
You can do that by using the
The
locale object is not tree-shakeable, meaning that all translations present in the object
will end up in the application bundle, whether it's being used or not.
|
okText | String | 'Ok' |
Text for Ok button. |
rtl | Boolean | false |
Right to left display. |
Customizing the appearance
While the provided pre-built themes are enough in many use cases, most of the times on top of adapting to a specific platform, you'd also like to match a brand or color scheme. Mobiscroll provides various ways to achieve this:
- Create custom themes using the theme builder - the custom themes can be also built using out theme builder, on a graphical user interface, without any coding, or the need for Sass support in your project.
- Create custom themes using Sass - use this, if you need multiple themes with different color variatons, in case you have pages with different colors, or you'd like to users to customize the colors of your app.
- Override the Sass color variables - the straightforward way to change the colors in one place throughout the application.
Override the Sass Color Variables
A convenient way to customize the colors of the Mobiscroll components is to override the Sass color variables.
Let's say your branding uses a nice red accent color, and you'd like that color to appear on the Mobiscroll components as well,
while still using platform specific themes (e.g. ios
on iOS devices, material
on Android devices, and mobiscroll
on desktop).
You can override the accent color for every theme:
$mbsc-ios-accent: #e61d2a;
$mbsc-material-accent: #e61d2a;
$mbsc-mobiscroll-accent: #e61d2a;
@import "~@mobiscroll/Javascript/dist/css/mobiscroll.javascript.scss"
You can also customize the colors on many levels:
- Theme specific variables (ex.
$mbsc-material-background
,$mbsc-ios-dark-text
) are applied to all components in a theme. Complete list of variables here. - Component specific global variables (ex.
$mbsc-card-background-light
,$mbsc-listview-text-dark
) are applied to all themes for a specific component. - Component and theme specific variables (ex.
$mbsc-ios-dark-form-background
,$mbsc-material-input-text
) are applied to a specific theme and a specific component.