Skip to main content
Version: 5.34.0

Popup API

Here is a comprehensive list of all the options, events and method the Popup component has.

Options​

Explore the following API options that help you easily configure the Popup component.

anchor​

HTMLElement

Specifies the anchor element for positioning, if display is set to 'anchored'.

Default value: undefined

animation​

boolean | "pop" | "slide-down" | "slide-up"

Animation to use when the component is opened or closed, if display is not set to 'inline'. Possible values:

  • 'pop'
  • 'slide-down'
  • 'slide-up'

If false, the animation is turned off.

Default value: undefined

ariaLabel​

string

Specifies the accessible name of the popup.

Default value: undefined

buttons​

Array<string | MbscPopupButton>

Buttons to display on the component. Each item of 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. Will display the caption specified by the okText option.
  • 'cancel' - Dismisses the popup. Will display the caption specified by the cancelText option.
  • 'close' - Closes the popup. Will display the caption specified by the closeText option.
  • 'set' - Approve action. Will display the caption specified by the setText option.

The MbscPopupButton type has the following properties:

  • color: "success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info" - Specifies the predefined color of the button
  • cssClass: string - A custom CSS class that will be applied to the element
  • disabled: boolean - Disabled state of the button
  • handler: MbscPopupPredefinedButton | (event: any) => void - Specifies what happens when the button is pressed. It can be a predefined button handler like 'set', 'cancel' or a custom function.
  • icon: string - When specified, it renders an icon on the button. It requires the name of the icon that should be displayed.
  • keyCode: number | "enter" | "esc" | "space" | Array<number | "enter" | "esc" | "space"> - The key code associated with the button to activate it from keyboard. Can be a single value or multiple value passed as an array. Predefined string values are: 'enter', 'esc', 'space'.
  • text: string - Sets the label of the button
  • variant: "outline" | "standard" | "flat" - The style of the button
Example for using predefined and custom buttons
[
  'set',
  {
    text: 'Custom',
    icon: 'checkmark',
    cssClass: 'my-btn',
    handler: function (event) {
      alert('Custom button clicked!');
    }
  },
  'cancel'
]
Example for using a predefined button handler
[
  'set',
  {
    text: 'Hide',
    handler: 'cancel',
    icon: 'close',
    cssClass: 'my-btn'
  }
]

Default value: undefined

closeOnEsc​

boolean

If true, the popup is closed when the ESC key is pressed.

Default value: true

closeOnOverlayClick​

boolean

If true, the popup is closed on overlay click or tap.

Default value: true

contentPadding​

boolean

When set to false, it will remove the default padding from the content area.

Default value: true

context​

string | HTMLElement

Specify the DOM element in which the component is rendered and positioned, if display is not 'inline'. Can be a selector string or a DOM element.

Default value: 'body'

cssClass​

string

Specifies a custom CSS class for the component.

info

The mbsc-no-padding class removes the built in padding of the popup content.

display​

MbscPopupDisplay

Controls the positioning of the component. Possible values are:

  • 'center' - The component appears as a popup at the center of the viewport.
  • 'inline' - The component is rendered inline.
  • 'anchored' - The component appears positioned to the element defined by the anchor option.
  • '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.

Default value: undefined

focusOnClose​

boolean

If true, after closing the popup the focus will be moved to the last focused element before the popup was opened.

Default value: true

focusOnOpen​

boolean

If true, the popup will receive the focus when opened.

Default value: true

focusTrap​

boolean

If true and display is not set to 'inline', focus won't be allowed to leave the popup.

Default value: true

fullScreen​

boolean

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.

Default value: false

headerText​

string

Text to display in the header.

Default value: undefined

height​

string | number

Sets the height of the component.

Default value: undefined

isOpen​

boolean

Specifies if the component is opened or not. Use it together with the onClose event, by setting it to false when the component closes.

Default value: false

maxHeight​

string | number

Sets the maximum height of the component. If not specified, on larger screens (>=768px width) it defaults to 600px.

Default value: undefined

maxWidth​

string | number

Sets the maximum width of the component.

Default value: undefined

responsive​

MbscResponsiveOptions<MbscPopupOptions>

Specifies different options 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 options for the given breakpoint.

info

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:

  • 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, you can use multiple, but each must have a unique name
    breakpoint: 600,
    display: 'center'
  },
  large: {
    display: 'anchored'
  }
}

Default value: undefined

scrollLock​

boolean

Disables page scrolling, if the content of the popup is not scrollable.

Default value: true

showArrow​

boolean

Show or hide the popup arrow, when display is 'anchored'.

Default value: true

showOverlay​

boolean

Show or hide the popup overlay.

Default value: true

theme​

string

Specifies 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.

info

Make sure that the theme you set is included in the downloaded package.

Default value: undefined

themeVariant​

"auto" | "light" | "dark"

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'.

Default value: undefined

touchUi​

boolean | "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.

Default value: 'auto'

width​

string | number

Sets the width of the component.

Default value: undefined

Events​

The Popup component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code.

onClose​

(args: MbscPopupCloseEvent, inst: PopupBase) => void

Triggered when the component is closed.

Parameters:

  • args - The event argument with the following properties:

    • source: string - Determines what triggered the close event. Can be one of 'set', 'cancel', 'ok', 'close', 'overlay', 'esc', 'scroll'.

  • inst - The component instance.

onDestroy​

(args: any, inst: any) => void

Triggered when the component is destroyed.

Parameters:

  • args - The event argument object.

  • inst - The component instance.

onInit​

(args: any, inst: any) => void

Triggered when the component is initialized.

Parameters:

  • args - The event argument object.

  • inst - The component instance.

onOpen​

(args: MbscPopupOpenEvent, inst: PopupBase) => void

Triggered when the component is opened.

Parameters:

  • args - The event argument with the following properties:

    • target: HTMLElement - The DOM element of the popup.

  • inst - The component instance.

onPosition​

(args: MbscPopupPositionEvent, inst: PopupBase) => void

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 in this handler. In that case, returning false from the handler function will prevent the built in positioning.

Parameters:

  • args - The event argument with the following properties:

    • target: HTMLElement - The DOM element of the popup.
    • windowWidth: number - The window width.
    • windowHeight: number - The window height.

  • inst - The component instance.

Localization​

The Popup component is fully localized. This covers date and time format, button copy, rtl and more.

cancelText​

string

Text for the "Cancel" button.

Default value: 'Cancel'

closeText​

string

Text for the "Close" button.

Default value: 'Close'

locale​

MbscLocale

Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a custom language module.

Supported values:

  • Arabic: localeAr, 'ar'
  • Bulgarian: localeBg, 'bg'
  • Catalan: localeCa, 'ca'
  • Czech: localeCs, 'cs'
  • Chinese: localeZh, 'zh'
  • Croatian: localeHr, 'hr'
  • Danish: localeDa, 'da'
  • Dutch: localeNl, 'nl'
  • English: localeEn or undefined, 'en'
  • English (UK): localeEnGB, 'en-GB'
  • Farsi: localeFa, 'fa'
  • German: localeDe, 'de'
  • Greek: localeEl, 'el'
  • Spanish: localeEs, 'es'
  • Finnish: localeFi, 'fi'
  • French: localeFr, 'fr'
  • Hebrew: localeHe, 'he'
  • Hindi: localeHi, 'hi'
  • Hungarian: localeHu, 'hu'
  • Italian: localeIt, 'it'
  • Japanese: localeJa, 'ja'
  • Korean: localeKo, 'ko'
  • Lithuanian: localeLt, 'lt'
  • Norwegian: localeNo, 'no'
  • Polish: localePl, 'pl'
  • Portuguese (Brazilian): localePtBR, 'pt-BR'
  • Portuguese (European): localePtPT, 'pt-PT'
  • Romanian: localeRo, 'ro'
  • Russian: localeRu, 'ru'
  • Russian (UA): localeRuUA, 'ru-UA'
  • Slovak: localeSk, 'sk'
  • Serbian: localeSr, 'sr'
  • Swedish: localeSv, 'sv'
  • Thai: localeTh, 'th'
  • Turkish: localeTr, 'tr'
  • Ukrainian: localeUa, 'ua'

Default value: undefined

okText​

string

Text for the "Ok" button.

Default value: 'Ok'

rtl​

boolean

Enables right-to-left display.

Default value: false

setText​

string

Text for the "Set" button.

Default value: 'Set'

Methods​

These methods are actions that can be performed on a component instance.

close​

() => void

Closes the component.

isVisible​

() => boolean

Returns if the component is opened or not.

open​

() => void

Opens the component.

position​

() => void

Recalculates the position of the component.

setOptions​

(opt: MbscPopupOptions) => void

Sets or updates options of the component. Options can be updated dynamically after the initialization.

It receives an options object as parameter. Calling setOptions will overwrite all the options that have a key in the options object parameter, and it will re-render the component.

inst.setOptions({
  themeVarian: 'dark',
})

Types​

MbscLocale​

Interface

Properties:

  • allDayText: string
  • amText: string
  • calendarSystem: MbscCalendarSystem
  • cancelText: string
  • clearText: string
  • closeText: string
  • dateFormat: string
  • dateFormatFull: string
  • dateFormatLong: string
  • dateText: string
  • dateWheelFormat: string
  • dayNames: Array<string>
  • dayNamesMin: Array<string>
  • dayNamesShort: Array<string>
  • daySuffix: string
  • dayText: string
  • eventText: string
  • eventsText: string
  • filterEmptyText: string
  • filterPlaceholderText: string
  • firstDay: number
  • fromText: string
  • hourText: string
  • minuteText: string
  • monthNames: Array<string>
  • monthNamesShort: Array<string>
  • monthSuffix: string
  • monthText: string
  • moreEventsPluralText: string
  • moreEventsText: string
  • nextMonthText: string
  • nextYearText: string
  • noEventsText: string
  • nowText: string
  • pmText: string
  • prevMonthText: string
  • prevYearText: string
  • rangeEndHelp: string
  • rangeEndLabel: string
  • rangeStartHelp: string
  • rangeStartLabel: string
  • rtl: boolean
  • secondText: string
  • selectedPluralText: string
  • selectedText: string
  • setText: string
  • timeFormat: string
  • timeText: string
  • timeWheels: string
  • toText: string
  • todayText: string
  • weekText: string
  • yearSuffix: string
  • yearText: string

MbscPopupButton​

Interface

Properties:

  • color: "success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info" - Specifies the predefined color of the button
  • cssClass: string - A custom CSS class that will be applied to the element
  • disabled: boolean - Disabled state of the button
  • handler: MbscPopupPredefinedButton | (event: any) => void - Specifies what happens when the button is pressed. It can be a predefined button handler like 'set', 'cancel' or a custom function.
  • icon: string - When specified, it renders an icon on the button. It requires the name of the icon that should be displayed.
  • keyCode: number | "enter" | "esc" | "space" | Array<number | "enter" | "esc" | "space"> - The key code associated with the button to activate it from keyboard. Can be a single value or multiple value passed as an array. Predefined string values are: 'enter', 'esc', 'space'.
  • text: string - Sets the label of the button
  • variant: "outline" | "standard" | "flat" - The style of the button

MbscPopupDisplay​

"center" | "bottom" | "top" | "anchored" | "inline" | "bubble"

MbscPopupPredefinedButton​

"set" | "cancel" | "ok" | "close"

MbscResponsiveOptions<MbscPopupOptions>​

Interface

The MbscResponsiveOptions<MbscPopupOptions> supports custom properties in the form:

[key:string]: MbscPopupOptions & {breakpoint?: number}

The keys are the names of the breakpoints, and the values are objects containing the options for the given breakpoint. The breakpoint property, when present, specifies the min-width in pixels. The options will take into effect from that width.

info

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:

  • xsmall - min-width: 0px
  • small - min-width: 576px
  • medium - min-width: 768px
  • large - min-width: 992px
  • xlarge - min-width: 1200px