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.
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.
<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.
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:
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. |
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:
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 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>;
};
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
|
|
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
|
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/React/dist/css/mobiscroll.react.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.