Modal
Modal is a dialog component used to display important information, warning prompts, or actions requiring confirmation on top of the current page. Modal provides multiple modal types (such as confirmation, warning, error, and success prompts), helping apps achieve a unified modal interaction experience.
Quick start
The following example demonstrates the basic implementation of the Modal component:
import Client, { shared, Modal, ModalAction } from '@shoplineos/app-bridge';
// 1. Initialize App Bridge.
const app = Client.createApp({
appKey: 'your-app-key',
host: shared.getHost(),
});
// 2. Create a Modal instance.
const modal = Modal.create(app);
// 3. Open a confirmation modal.
modal.open({
type: 'confirm',
title: 'Confirm Deletion',
content: 'Are you sure you want to delete the product? This operation cannot be undone.',
onOk: () => {
Message.create(app).success('Done');
},
onCancel: () => {
Message.create(app).info('Canceled');
},
});
After you call the open() method, the modal will appear on the page. The following figure shows the effect of a confirmation modal:

API methods
open()
(config: ModalProps): void
Opens the modal.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| config | ModalProps | Modal configuration. | Yes |
Example
// Confirmation modal
modal.open({
type: 'confirm',
title: 'Confirm Action',
content: 'Are you sure you want to proceed?',
});
// Risk modal
modal.open({
type: 'danger',
title: 'Risky Operation',
content: 'This operation will permanently delete the data and cannot be undone.',
});
// Error prompt modal
modal.open({
type: 'error',
title: 'Operation Failed',
content: 'Save failed. Try again later.',
});
// Success prompt modal
modal.open({
type: 'success',
title: 'Operation Successful',
content: 'Product saved successfully.',
});
// Warning modal
modal.open({
type: 'warn',
title: 'Warning',
content: 'You have unsaved changes. Are you sure you want to leave?',
});
// Information prompt modal
modal.open({
type: 'info',
title: 'Tip',
content: 'This feature is coming soon. Stay tuned.',
});
subscribe()
(action: ModalAction, callback: () => void, once?: boolean): () => void
Subscribes to modal action events (such as confirmation and cancellation).
The subscribe() method is deprecated. When writing new code, use the onOk and onCancel callbacks in modal.open(config) instead.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| action | ModalAction | The action type to subscribe to. | Yes |
| callback | () => void | The callback function triggered when the action occurs. | Yes |
| once | boolean | Whether to automatically unsubscribe after one trigger.
| No |
Return value
Returns an unsubscribe function. Calling it will cancel the current subscription.
Example
// Subscribe to the confirmation event.
const unsubscribe = modal.subscribe(ModalAction.MODAL_SAVE, () => {
console.log('Operation is confirmed.');
// Execute corresponding business logic
});
// Unsubscribe.
unsubscribe();
// Subscribe to a one-time event (automatically unsubscribed from after a trigger).
modal.subscribe(
ModalAction.MODAL_SAVE,
() => {
console.log('This callback will only execute once.');
},
true,
);
unsubscribe()
(action: ModalAction): void
Unsubscribes from all listeners for a specified action.
The unsubscribe() method is deprecated and should only be used to maintain legacy code.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| action | ModalAction | The action type to unsubscribe from. | Yes |
Example
// Unsubscribe from all listeners for the MODAL_SAVE action.
modal.unsubscribe(ModalAction.MODAL_SAVE);
Type definitions
ModalProps
Configuration parameters for the open() method.
| Parameter | Type | Description | Required |
|---|---|---|---|
| type | 'confirm' | 'danger' | 'error' | 'warn' | 'info' | 'success' | The modal type, which determines the modal's style and icon. | Yes |
| title | string | The modal title text. | Yes |
| content | string | The modal content text. | Yes |
| onOk | () => void | Promise<void> | The callback function executed when the confirm button is clicked. It corresponds to the ModalAction.MODAL_SAVE action in the subscribe() method. | No |
| onCancel | () => void | Promise<void> | The callback function executed when the cancel button is clicked or the modal is closed. It corresponds to the ModalAction.MODAL_CLOSE action in the subscribe() method. | No |
Modal types:
| Type | Description | Use case |
|---|---|---|
confirm | Confirmation modal | Operations requiring user confirmation |
danger | Risk modal | Risky or irreversible operations |
error | Error prompt modal | Operation failures or errors |
warn | Warning modal | Warning messages or important notes |
info | Information prompt modal | General information prompts |
success | Success prompt modal | Feedback for successful operations |
ModalAction
Subscribe to the following actions via the subscribe() method to listen to various modal events.
| Action Type | Description | Trigger condition | Callback parameter |
|---|---|---|---|
MODAL_SAVE | Confirm | Triggered when the confirm button is clicked. | None |
MODAL_CLOSE | Cancel or close | Triggered when the cancel button is clicked or the modal is closed. | None |