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.

JSX
import { useCallback, useState } from 'react';
import { Popup } from '@mobiscroll/react';

const App = () => {
  const [isPopupOpen, setOpen] = useState(false);

  const openPopup = useCallback(() => {
    setOpen(true);
  }, []);

  const closePopup = useCallback(() => {
    setOpen(false);
  }, []); 
  
  return <>
    <Popup isOpen={isPopupOpen} onClose={closePopup}>
      <h3>Hi</h3>
      <p>Are you feeling good today?</p>
    </Popup>
    <button onClick={openPopup}>Open popup</button>
  </>;
}

Passing options

Options can be passed as props for the component.

JSX
<Popup theme="ios" buttons={['ok', 'cancel']}>
  ...
</Popup>

Changing options

Props are dynamic, so if you pass a variable to an option instead of a static value, the component will be updated when the variable is changed.

JSX
import { useCallback, useState } from 'react';
import { Popup } from '@mobiscroll/react';

const App = () => {
  const [myDisplay, setDisplay] = useState('center');

  const setDisplayAnchored = useCallback(() => {
    setDisplay('anchored');
  }, []);

  const setDisplayBottom = useCallback(() => {
    setDisplay('bottom');
  }, []);
  
  return <>
    <Popup display={myDisplay}>
      ...
    </Popup>
    <button onClick={setDisplayAnchored}>Set anchored display</button>
    <button onClick={setDisplayBottom}>Set bottom display</button>
  </>;
}

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

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: function (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 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:
  • 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 make an option dynamic, you can pass a variable as option value. Whenever the value of the variable changes, the component will be re-rendered.

const App = () => {
        
  const [myTheme, setMyTheme] = useState('ios');

  const changeTheme = useCallback(() => {
    // Changes the theme to Material
    setMyTheme('material');
  }, []);

  return <div>
    <Popup theme={myTheme} />
    <button onClick={changeTheme}>Change theme</button>
  </div>;
};
For performance reasons on re-render we compare prop 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

Name Description
onClose(event, inst) Triggered when the component is closed.

Parameters

  • event: Object - The event object.
    • source: String - Determins what triggered the close event. Can be one of 'set', 'cancel', 'ok', 'close', 'overlay', 'esc', 'scroll'.
  • inst: Object - The instance object of the popup.

Example

<mobiscroll.Popup
    onClose={function (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

<mobiscroll.Popup
    onDestroy={function (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

<mobiscroll.Popup
    onInit={function (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

<mobiscroll.Popup
    onOpen={function (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

<mobiscroll.Popup
    onPosition={function (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, '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'
  • Vietnamese: localeVi, 'vi'
import { Eventcalendar, localeDe } from '@mobiscroll/react';

export function MyComponent() {
  return <Eventcalendar locale={localeDe} />;
}

In some cases it's more convenient to set the locale using the language code string. You can do that by using the locale object, which contains all translations by language codes as keys.

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.
import { Eventcalendar, locale } from '@mobiscroll/react';

export function MyComponent() {
  return <Eventcalendar locale={locale['de']} />;
}
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/React/dist/css/mobiscroll.react.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.

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.

Example on configuring the styles
// include the ios theme
$mbsc-ios-theme: true;

// include the components:
$mbsc-datepicker: true;
$mbsc-eventcalendar: true;
        
@import "@mobiscroll/react/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.

It's important that you override the variables BEFORE the scss file import, otherwise it won't make any difference.

Here's the complete list of the components and themes that can be used:

Some components use others internally, so it might happen that even though you don't want to include some styles, they will still end up in your bundle.
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.