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 buttoncssClass
: string - A custom CSS class that will be applied to the elementdisabled
: boolean - Disabled state of the buttonhandler
: 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 buttonvariant
: "outline" | "standard" | "flat" - The style of the button
[
'set',
{
text: 'Custom',
icon: 'checkmark',
cssClass: 'my-btn',
handler: function (event) {
alert('Custom button clicked!');
}
},
'cancel'
]
[
'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.
The mbsc-no-padding
class removes the built in padding of the popup content.
display
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.
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: 0pxsmall
- min-width: 576pxmedium
- min-width: 768pxlarge
- min-width: 992pxxlarge
- 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.
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'
orundefined
- 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
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
orundefined
,'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
: stringamText
: stringcalendarSystem
: MbscCalendarSystemcancelText
: stringclearText
: stringcloseText
: stringdateFormat
: stringdateFormatFull
: stringdateFormatLong
: stringdateText
: stringdateWheelFormat
: stringdayNames
: Array<string>dayNamesMin
: Array<string>dayNamesShort
: Array<string>daySuffix
: stringdayText
: stringeventText
: stringeventsText
: stringfilterEmptyText
: stringfilterPlaceholderText
: stringfirstDay
: numberfromText
: stringhourText
: stringminuteText
: stringmonthNames
: Array<string>monthNamesShort
: Array<string>monthSuffix
: stringmonthText
: stringmoreEventsPluralText
: stringmoreEventsText
: stringnextMonthText
: stringnextYearText
: stringnoEventsText
: stringnowText
: stringpmText
: stringprevMonthText
: stringprevYearText
: stringrangeEndHelp
: stringrangeEndLabel
: stringrangeStartHelp
: stringrangeStartLabel
: stringrtl
: booleansecondText
: stringselectedPluralText
: stringselectedText
: stringsetText
: stringtimeFormat
: stringtimeText
: stringtimeWheels
: stringtoText
: stringtodayText
: stringweekText
: stringyearSuffix
: stringyearText
: string
MbscPopupButton
Interface
Properties:
color
: "success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info" - Specifies the predefined color of the buttoncssClass
: string - A custom CSS class that will be applied to the elementdisabled
: boolean - Disabled state of the buttonhandler
: 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 buttonvariant
: "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.
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: 0pxsmall
- min-width: 576pxmedium
- min-width: 768pxlarge
- min-width: 992pxxlarge
- min-width: 1200px