Skip to content

Modal Components

Overview

A Modal Component is a custom component pre-configured for use as an overlay dialog. A Wizard Modal is a variant that adds multi-step navigation, letting you break a flow across several component pages. Both types are opened programmatically using the $modal built-in service, which is injectable anywhere in a page or component.

What You Will Learn

  • What Modal Components and Wizard Modals are and when to use each
  • How to open a modal using the $modal service and pass data to it
  • How to pass values back to the caller using exported declarations
  • What declarations are generated when you create a Modal Component or Wizard Modal
  • How the Wizard Modal manages page navigation and state

When To Use This

Use a Modal Component when you need a dialog that overlays the current page — for example, a confirmation prompt, a detail view, or a data-entry form that should not navigate away from the current context. Use a Wizard Modal when the interaction spans multiple steps that need to be completed in sequence.

The $modal Service

$modal is a built-in service available in any page or component. Inject it via the Declarations panel and call it from a function — for example, from a button's click event handler.

Both $modal.open() and $modal.confirm() return Promises. To use await in a function body, make sure the Async checkbox is checked in the function editor dialog.

Opening a Modal

Call $modal.open() to display a modal component as an overlay:

1
$modal.open(componentName, componentProperties, options)
Parameter Required Description
componentName Yes The name of the Modal Component to display.
componentProperties No An object of initial values for the component's exported properties. This is how data is passed into the modal.
options No Additional configuration for the modal (see Modal Options below).

$modal.open() returns a Promise that resolves when the modal closes. The resolved value is an object containing result plus any other exported properties on the modal component — this is how data is passed back to the caller.

1
2
3
4
const response = await $modal.open('ConfirmDeleteModal', { itemName: record.name });
if (response.result === 'ok') {
  // proceed with deletion
}

The optional options parameter accepts the following properties:

Property Type Description
animation string Animation type for the modal: "fade", "flip", "popup", or "slide".
animationDuration number Duration of the modal animation in milliseconds.
closeOnBackdropClick boolean When true, clicking the backdrop closes the modal.
componentLocation string The parent component or app name used to locate the component.
style string Inline CSS style applied to the modal content container.

Showing a Confirmation Dialog

$modal.confirm() displays a generic confirmation modal without requiring a dedicated Modal Component. Use it for simple yes/no or multi-choice prompts.

1
$modal.confirm({ message, title, buttons })

It accepts a single configuration object with the following properties:

Property Required Description
message Yes The message text displayed in the modal body.
title Yes The title displayed in the modal header.
buttons Yes An array of button objects defining the available actions (see below).

Each button object in the buttons array has the following properties:

Property Required Description
type Yes Visual style of the button: "default", "primary", or "secondary".
label Yes The text displayed on the button.
value No The value returned when this button is clicked. If omitted, the button's label is used as the value.

$modal.confirm() returns a Promise that resolves to the value (or label) of the button the user clicked. If buttons is omitted, the modal shows default OK and Cancel buttons — the promise resolves to true when OK is clicked and false when Cancel is clicked.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const result = await $modal.confirm({
  message: 'Are you sure you want to delete this record? This action cannot be undone.',
  title: 'Confirm Delete',
  buttons: [
    { type: 'default', label: 'Cancel', value: 'cancel' },
    { type: 'primary', label: 'Delete', value: 'ok' }
  ]
});
if (result === 'ok') {
  // proceed with deletion
}

Required Exported Declarations

For $modal to work correctly, a Modal Component must have the following two exported declarations:

Declaration Type Description
onClose Function Called to close the modal. Wire this to your close, cancel, and OK buttons.
result Property The value returned to the caller when the modal closes. Conventionally set to "ok" or "cancel" before calling onClose.

These declarations are exported so the $modal service can read result and invoke onClose at the appropriate time. Any additional exported properties you define on the component are also included in the resolved promise value.

When you create a Modal Component (see Creating Components), Bellini generates a component with a standard dialog layout and pre-wired declarations.

Area Contents
Header Modal title ("Title" by default, left-aligned) and an × close button (right-aligned)
Body An empty container — add your own UI here
Footer Cancel and OK buttons
Declaration Exported Description
onClose Yes Closes the modal. Bound to the × button in the header.
result Yes The modal result returned to the caller.
onOkClick No Sets result to "ok" then calls onClose. Bound to the OK button.
onCancelClick No Sets result to "cancel" then calls onClose. Bound to the Cancel button.

You can modify onOkClick and onCancelClick to add validation or any other logic before closing.

Wizard Modal

A Wizard Modal extends the Modal Component pattern with multi-step navigation. When you create one, Bellini generates the modal component and a configurable number of page components that are embedded in the modal body.

Wizard Modal Dialog

The Wizard Modal creation wizard has the same fields as the Component wizard, plus one additional field:

  • Total Number of Pages — the number of page components to generate for the wizard steps.

Each generated page component is embedded in the modal body. Its visibility is controlled by a Display expression that compares $ctrl.currentPageIndex to the page's position (e.g. $ctrl.currentPageIndex === 0 for the first page, === 1 for the second, and so on).

Generated Layout

Area Contents
Header Modal title and × close button
Body One slot per wizard page; only the page matching currentPageIndex is visible
Footer Previous, Next, Cancel, and Finish (instead of OK) buttons

Generated Declarations

In addition to the standard modal declarations, a Wizard Modal includes:

Declaration Exported Description
onClose Yes Closes the modal.
result Yes The modal result returned to the caller.
onOkClick No Sets result to "ok" and calls onClose. Bound to the Finish button.
onCancelClick No Sets result to "cancel" and calls onClose. Bound to the Cancel button.
currentPageIndex No The index of the currently visible page (starts at 0). Controls which page is displayed.
totalPages No The total number of wizard pages.
onNextClick No Increments currentPageIndex. Bound to the Next button.
onPreviousClick No Decrements currentPageIndex. Bound to the Previous button.
canNextPage No Bound to the Next button's Disabled property. Returns false on the last page.
canPreviousPage No Bound to the Previous button's Disabled property. Returns false on the first page.
canFinish No Bound to the Finish button's Disabled property. Returns true when the current page is the last page. Override this for custom finish conditions.

Opening a Wizard Modal

Wizard Modals are opened exactly like regular modals using $modal.open():

1
2
3
4
const response = await $modal.open('OnboardingWizard', { userId: currentUser.id });
if (response.result === 'ok') {
  // wizard completed
}

Helpful Resources