Modal

The Modal is the right choice for any kind of popup or dialog that you would like to show prominently on top of the regular app UI. Like the Container and Form components, the Modal acts as a host of child components with its own grid system. Due to its fixed position on the screen, you cannot change the component position or its dimensions by dragging and dropping.
The modal always keeps its fixed position
Accessing a modal
Since the Modal is usually not visible on the canvas, you might wonder how to access a closed modal in the app editor. You can use the explorer tab of the left-hand pane to open any modal component with a click.
Accessing a closed modal in the editor
It is not possible to drag another component from outside a modal into a modal. Until this issue is resolved, we recommend using copy-paste to achieve this result:

1. Select the component(s) that you would like to move to a modal
2. Use CMD+c (Mac) / CTRL+c (Win) to copy the selected component(s)
3. Open the target modal via the explorer tab and make sure it is selected
4. Use CMD+v (Mac) / CTRL+v (Win) to paste the copied component(s) into the modal
5. Delete the copied component(s) outside the modal
Modal sizing
Instead of resizing a Modal in the usual way with drag-and-drop, the Modal dimensions are determined by its "Width" and "Height" properties. You can place any valid CSS expression, for example, 80%, 500px, 80vh or even calc(100% - 50px), and these dimensions are applied to the Modal.
The Modal has a minimum height of 280px and minimum width of 360px to maintain basic usability that cannot be changed.
We recommend using relative sizing as much as possible. Absolute dimensions in pixels might lead to undesired overflow on small screens, or weirdly small modals on large screens.
Properties
The Modal component offers the following configuration properties.
Property
Type
Default value
Behavior
Blurred background
boolean
true
Determines whether a dark blurred background should cover the UI.
Close on escape
boolean
true
When set to true, an open modal closes when the user hits the escape key. Otherwise, this keypress is ignored.
Close on outside click
boolean
true
When set to true, an open modal closes when the user clicks outside its content, i.e. on the blurred background. It is recommended to disable this for complex modals, of which the user would not like to lose state easily.
Header text
stringWithJs
'Header'
The text to be displayed in the header. Only available when the "Show header" property is set to true.
Height
string
'60vh'
CSS height of the modal. See considerations above.
Scrollable
boolean
true
Determines whether the modal content is scrollable or not. When set to false, overflowing content is not be accessible for the end user.
Show close icon
boolean
true
Determines whether there should be the "x" icon in the top-right corner for closing the modal. In case "Show header" is set to false, the icon might overlap with the modal content.
Show header
boolean
true
Determines whether the modal should have a header. When set to true, the header text can be configured via the "Header text" property.
Visible
boolean
false
The "Visible" property behaves differently than in other components. For the Modal, this property determines whether the modal is open or closed. You might apply a dynamic JavaScript expression here, but usually a modal should be opened or closed explicitly using the exposed functions.
Width
string
'60vw'
CSS width of the modal. See considerations above.
Review the notes regarding the "Scrollable" property in the Container reference, the Modal behaves in exactly the same way.
An open modal is closed automatically when another modal is opened. This means, that you do not need to close a modal explicitly when opening another modal.
Events
The Modal offers two events to associate actions with:
On show: This action is executed whenever the modal is opened, regardless of the reason ("Visible" property, show() function, selecting the component in the explorer tab of the app editor).
On hide: This action is executed when a modal is closed, regardless of the reason.
To maintain a pleasant user experience, the "On show" action is executed asynchronously with displaying the modal. A long-running action does not block the modal render, but leads to a spinner until the action run has finished. This is useful, for example, fetching data from sources when a modal is opened.
Asynchronous execution of "On show" action
The "On hide" action is executed asynchronously as well, i.e. the modal will be closed instantly, but the action might still be running. Again, this leads to a more snappy UI and better user experience. There is currently no way to modify this action execution behavior.
API
The Modal exposes the following API in the JavaScript runtime environment.
Property / Function
Type
Behavior
blurredBackground
boolean
Current boolean value of the "Blurred background" property.
close()
() => void
Closes the modal and executes the "On hide" action asynchronously. Noop in case the modal is not open.
closeOnEscape
boolean
Current boolean value of the "Close on escape" property.
closeOnOutsideClick
boolean
Current boolean value of the "Close on outside click" property.
headerText
string
Current string value of the "Header text" configuration.
height
string
Current css-string value of the "Height" property.
hide()
() => void
Alias for close().
setBlurredBackground(value)
(value: boolean) => void
Sets the "Blurred background" property to the provided boolean value.
setCloseOnEscape(value)
(value: boolean) => void
Sets the "Close on escape" property to the provided boolean value.
setCloseOnOutsideClick(value)
(value: boolean) => void
Sets the "Close on outside click" property to the provided boolean value.
setHeaderText(value)
(value: string) => void
Sets the header text to the provided string value.
setHeight(value)
(value: string) => void
Sets the "Height" property to the provided string value. The value should be a valid CSS expression. This is not validated.
setShowHeader(value)
(value: boolean) => void
Adjusts the flag whether the header text should be displayed to the provided boolean value.
setWidth(value)
(value: string) => void
Sets the "Width" property to the provided string value. The value should be a valid CSS expression. This is not validated.
show()
() => void
Opens the modal and executes the "On show" action asynchronously. Closes any other modal that is currently open. Noop in case the modal is already open.
showHeader
boolean
Current boolean value of the "Show header" configuration.
width
string
Current css-string value of the "Width" property.

Property	Type	Default value	Behavior
Blurred background	`boolean`	`true`	Determines whether a dark blurred background should cover the UI.
Close on escape	`boolean`	`true`	When set to `true`, an open modal closes when the user hits the escape key. Otherwise, this keypress is ignored.
Close on outside click	`boolean`	`true`	When set to `true`, an open modal closes when the user clicks outside its content, i.e. on the blurred background. It is recommended to disable this for complex modals, of which the user would not like to lose state easily.
Header text	`stringWithJs`	`'Header'`	The text to be displayed in the header. Only available when the "Show header" property is set to `true.`
Height	`string`	`'60vh'`	CSS height of the modal. See considerations above.
Scrollable	`boolean`	`true`	Determines whether the modal content is scrollable or not. When set to `false`, overflowing content is not be accessible for the end user.
Show close icon	`boolean`	`true`	Determines whether there should be the "x" icon in the top-right corner for closing the modal. In case "Show header" is set to `false`, the icon might overlap with the modal content.
Show header	`boolean`	`true`	Determines whether the modal should have a header. When set to `true`, the header text can be configured via the "Header text" property.
Visible	`boolean`	`false`	The "Visible" property behaves differently than in other components. For the `Modal`, this property determines whether the modal is open or closed. You might apply a dynamic JavaScript expression here, but usually a modal should be opened or closed explicitly using the exposed functions.
Width	`string`	`'60vw'`	CSS width of the modal. See considerations above.

Property / Function	Type	Behavior
`blurredBackground`	`boolean`	Current boolean value of the "Blurred background" property.
`close()`	`() => void`	Closes the modal and executes the "On hide" action asynchronously. Noop in case the modal is not open.
`closeOnEscape`	`boolean`	Current boolean value of the "Close on escape" property.
`closeOnOutsideClick`	`boolean`	Current boolean value of the "Close on outside click" property.
`headerText`	`string`	Current string value of the "Header text" configuration.
`height`	`string`	Current css-string value of the "Height" property.
`hide()`	`() => void`	Alias for `close().`
`setBlurredBackground(value)`	`(value: boolean) => void`	Sets the "Blurred background" property to the provided boolean value.
`setCloseOnEscape(value)`	`(value: boolean) => void`	Sets the "Close on escape" property to the provided boolean value.
`setCloseOnOutsideClick(value)`	`(value: boolean) => void`	Sets the "Close on outside click" property to the provided boolean value.
`setHeaderText(value)`	`(value: string) => void`	Sets the header text to the provided string value.
`setHeight(value)`	`(value: string) => void`	Sets the "Height" property to the provided string value. The value should be a valid CSS expression. This is not validated.
`setShowHeader(value)`	`(value: boolean) => void`	Adjusts the flag whether the header text should be displayed to the provided boolean value.
`setWidth(value)`	`(value: string) => void`	Sets the "Width" property to the provided string value. The value should be a valid CSS expression. This is not validated.
`show()`	`() => void`	Opens the modal and executes the "On show" action asynchronously. Closes any other modal that is currently open. Noop in case the modal is already open.
`showHeader`	`boolean`	Current boolean value of the "Show header" configuration.
`width`	`string`	Current css-string value of the "Width" property.

Last modified 4mo ago