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.

Template
<mbsc-popup #myPopup>
  <h3>Hi</h3>
  <p>How are you feeling today?</p>
</mbsc-popup>
<button (click)="myPopup.open()">Open popup</button>`

Passing options

Options can be passed as attributes for the component.

Template
<mbsc-popup theme="ios" [buttons]="['ok', 'cancel']">
  ...
</mbsc-popup>

Alternatively you can pass the options as a single object using the [options] binding.

Component
import { MbscPopupOptions } from '@mobiscroll/angular';

@Component({
  selector: 'app-example',
  template: 'example.html'
})
export class ExampleComponent {
  myPopupOptions: MbscPopupOptions = {
    theme: 'ios',
    buttons: ['ok', 'cancel']
  };
}
Template
<mbsc-popup [options]="myPopupOptions">
  ...
</mbsc-popup>

Changing options

You can bind component properties to the options, this way they can be dynamic.

Component
@Component({
  selector: 'app-example',
  template: 'example.html'
})
export class ExampleComponent {
  myDisplay = 'center';

  setDisplay(display: string) {
    this.myDisplay = display;
  }
}
Template
<mbsc-popup [display]="myDisplay">
  ...
</mbsc-popup>
<button (click)="setDisplay('anchored')">Set anchored display</button>
<button (click)="setDisplay('bottom')">Set bottom display</button>

For many more examples - simple and complex use-cases - check out the popup demos for angular.

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:
  • 'pop'
  • 'slide-down'
  • 'slide-up'
If 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:
  • 'ok' - Approve action (if applicable). It's the same as the 'set' button, but will display the caption specified by the okText setting. Just like the 'set' button, it will trigger the onSet event, when pressed.
  • 'cancel' - Dismisses the popup.
To modify the text of the predefined buttons, you can use the okText , cancelText options.

If an object, it may have the following properties:
  • text String - Text of the button.
  • handler String, Function - The function which will run when the button is pressed. If a string, it must be one of the predefined button handlers:
    • 'set' - Approve action (if applicable).
    • 'cancel' - Dismisses the popup.
  • icon String (Optional) - Icon of the button.
  • cssClass String (Optional) - Css class of the button.
  • keyCode Number, String, Array (Optional) - The key code associated with the button to activate it from keyboard. Can be a single value or multiple value passed as an array. Predifine string values are: 'enter', 'esc' and 'space'.
Predefined and custom buttons example
buttons: [
    'set',
    {
        text: 'Custom',
        icon: 'checkmark',
        cssClass: 'my-btn', 
        handler: (event) => {
            alert('Custom button clicked!');
        }
    },
    'cancel'
]
Predefined button handler example
buttons: [
    'set',
    {
        text: 'Hide',
        handler: 'cancel',
        icon: 'close',
        cssClass: 'my-btn'
    }
]
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.
display String undefined Controls the positioning of the component. Possible options:
  • 'center' - The component appears as a popup at the center of the viewport.
  • 'inline' - If called on div element, the component is placed inside the div (overwriting existing content), otherwise is placed after the original element.
  • 'anchored' - The component appears positioned to the element defined by the anchor option. By default the anchor is the original element.
  • 'top' - The component appears docked to the top of the viewport.
  • 'bottom' - The component appears docked to the bottom of the viewport.

The default display mode depends on the theme, it defaults to 'bottom' for the iOS theme and to 'center' for all other themes.

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.
isOpen Boolean undefined Specifies wether the popup is opened or not. Use it together with the onClose event, by setting it to false when the popup closes.
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 viewport 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.

There are five predefined breakpoints:
  • xsmall - min-width: 0px
  • small - min-width: 576px
  • medium - min-width: 768px
  • large - min-width: 992px
  • xlarge - min-width: 1200px
Custom breakpoints can be defined by passing an object containing the breakpoint property specifying the min-width in pixels. Example:
responsive: {
    small: {
        display: 'bottom'
    },
    custom: { // Custom breakpoint
        breakpoint: 600,
        display: 'center'
    },
    large: {
        display: 'anchored'
    }
}
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 'auto' or undefined, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme.

Supplied themes:
  • 'ios' - iOS theme
  • 'material' - Material theme
  • 'windows' - Windows theme
It's possible to modify theme colors or create custom themes.
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:
  • 'light' - Use the light variant of the theme.
  • 'dark' - Use the dark variant of the theme.
  • 'auto' or undefined - Detect the preferred system theme on devices where this is supported.

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 '-dark', e.g.: 'my-theme' and 'my-theme-dark'.

touchUi Boolean, String 'auto'

Use true to render a touch optimized user interface, or false for a user interface optimized for pointer devices (mouse, touchpad).

Can be used with the responsive option to change the user interface based on viewport width.

If set to 'auto', the touch UI will be automatically enabled based on the platform.

width Number, String undefined Sets the width of the popup container. This will take no effect in inline display mode.

Setting options dynamically

To bind an option to a component's property, place the option name in square brackets ([]). Whenever the component property is changed, the option is dynamically updated with the new property value.

<mbsc-popup [theme]="myTheme"></mbsc-popup>
myTheme = 'ios';

changeTheme() {
  // Changes the theme to Material
  this.myTheme = 'material';
}
For performance reasons Angular's change detection compares values by reference. This means, that in case of options, which accept complex data structures, like arrays or objects, changes made inside the array or object won't be detected. To ensure the change is detected, always pass a new array or object reference.

Events

Using arrow functions is recommended so you have access to your outer component instance inside event handlers through this reference.
Name Description
onClose(event, inst) Triggered when the component is closed.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the popup.

Example

export class MyExample {
    settings: any = {
        onClose: (event, inst) => {
        }
    }
}
onDestroy(event, inst) Triggered when the component is destroyed.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the popup.

Example

export class MyExample {
    settings: any = {
        onDestroy: (event, inst) => {
        }
    }
}
onInit(event, inst) Triggered when the component is initialized.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the popup.

Example

export class MyExample {
    settings: any = {
        onInit: (event, inst) => {
        }
    }
}
onOpen(event, inst) Triggered when the component is opened.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
  • inst: Object - The instance object of the popup.

Example

export class MyExample {
    settings: any = {
        onOpen: (event, inst) => {
        }
    }
}
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

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
    • windowWidth: Number - The window width.
    • windowHeight: Number - The window height.
  • inst: Object - The instance object of the popup.

Example

export class MyExample {
    settings: any = {
        onPosition: (event, inst) => {
        }
    }
}

Methods

Name Description
close() Closes the component.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.close();
isVisible() Returns a boolean indicating whether the component is visible or not.

Returns: Boolean

  • True if the component is visible, false if it's not.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.isVisible();
open() Opens the component.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.open();
position() Recalculates the position of the component (if not inline).

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.position();

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:
  • Arabic: localeAr
  • Bulgarian: localeBg
  • Catalan: localeCa
  • Czech: localeCs
  • Chinese: localeZh
  • Croatian: localeHr
  • Danish: localeDa
  • Dutch: localeNl
  • English: localeEn or undefined
  • English (UK): localeEnGB
  • Farsi: localeFa
  • German: localeDe
  • Greek: localeEl
  • Spanish: localeEs
  • Finnish: localeFi
  • French: localeFr
  • Hebrew: localeHe
  • Hindi: localeHi
  • Hungarian: localeHu
  • Italian: localeIt
  • Japanese: localeJa
  • Korean: localeKo
  • Lithuanian: localeLt
  • Norwegian: localeNo
  • Polish: localePl
  • Portuguese (Brazilian): localePtBR
  • Portuguese (European): localePtPT
  • Romanian: localeRo
  • Russian: localeRu
  • Russian (UA): localeRuUA
  • Slovak: localeSk
  • Serbian: localeSr
  • Thai: localeTh
  • Swedish:localeSv
  • Turkish: localeTr
  • Ukrainian: localeUa
  • Vietnamese: localeVi
import { localeDe } from '@mobiscroll/angular';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html'
})
export class AppComponent {
    myLocale = localeDe;
}
<mbsc-eventcalendar [locale]="myLocale"></mbsc-eventcalendar>
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:

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/Angular/dist/css/mobiscroll.angular.scss"
It's important that you override the variables BEFORE the scss file import, otherwise it won't make any difference.
Here's a complete guide on how to set up Mobiscroll with SASS support

You can also customize the colors on many levels:

  1. Theme specific variables (ex. $mbsc-material-background, $mbsc-ios-dark-text) are applied to all components in a theme. Complete list of variables here.
  2. Component specific global variables (ex. $mbsc-card-background-light, $mbsc-listview-text-dark) are applied to all themes for a specific component.
  3. 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.

Hereinafter you will see all the variables that are specific to the Popup component or affect its look: