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.
$('#mypopup').mobiscroll().popup();
$('#show').click(function(){
$('#mypopup').mobiscroll('open');
return 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.
$('#mypopup').mobiscroll().popup({
theme: 'ios',
buttons: ['ok', 'cancel']
});
Changing options
After initialization the options can be changed any time by using the setOptions method.
$('#mypopup').mobiscroll('setOptions', {
theme: 'material',
buttons: ['close']
});
For many more examples - simple and complex use-cases - check out the popup demos for jquery.
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.
$('#elm').mobiscroll().popup({
theme: 'ios'
});
// Changes the theme to Material
$('#elm').mobiscroll('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/JQuery/dist/css/mobiscroll.jquery.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.
Tree Shaking for styles
Tree shaking is a term commonly used in web development and particularly in JavaScript for unused code removal. Since websites are served (mostly) over the network, loading times depend on content size, so minification and unused content elimination plays a major role in making webapps fluid.
For the JavaScript part, popular frameworks already have the treeshaking built in, so the components that are not used will be left out from the built project.
Eliminating unused styles
In case of the styles, leaving out the unused rules is not as straight forward.
The overarching idea is that CSS selectors match elements in the DOM, and those elements in the DOM come from all sorts of places:
your static templates, dynamic templates based on server-side state, and of course, JavaScript, which can manipulate the DOM in
any way at all, including pull things from APIs and third parties.
Sass variables to the rescue
The Mobiscroll Library comes with a modular SASS bundle, that can be configured which component styles and which themes to leave in and out for the compiled css file.
Every component and theme has a SASS variable that can be turned on or off. If the variable is falsy the styles that it needs will not be added to the bundle.
// include the ios theme
$mbsc-ios-theme: true;
// include the components:
$mbsc-datepicker: true;
$mbsc-eventcalendar: true;
@import "@mobiscroll/jquery/dist/css/mobiscroll.modular.scss"
In the above example the styles needed for the eventcalendar and datepicker will be included and only for the ios theme. All other components (like select or grid-layout) and all other themes will be left out from the bundle.
Here's the complete list of the components and themes that can be used:
$mbsc-datepicker
$mbsc-eventcalendar
$mbsc-forms
$mbsc-grid-layout
$mbsc-popup
$mbsc-select
$mbsc-ios-theme
$mbsc-material-theme
$mbsc-windows-theme
For example if you don't want to include the form components (input, button, segmented, etc...), but you are using the select component, the styles for the mobiscroll buttons, will still be in, because of the dependency.
Accessibility
Keyboard Support
All the picker components and the popup listen for the Space
or the Enter
keys to open the popup.
The Esc
key can be used to cancel, while the Enter
key is for the set action.
The focusTrap option by default won't let the focus to leave the popup.