Overview
Dashboard modals are popup dialogs triggered from dashboard pages or plugins. They consist of three files and use the Dashboard SDK for lifecycle control via
openModal()
and
closeModal()
.
Quick Reference
Task
Method
Example
Create modal
Create 3 files in
src/extensions/dashboard/modals/openModal with your modal id.
// e.g.
// import { dashboard } from '@wix/dashboard';
// function MyComponent() {
// return ;
// }
const
Modal
:
FC
=
(
)
=>
{
return
(
<
WixDesignSystemProvider features
=
{
{
newColorsBranding
:
true
}
}
< CustomModalLayout width = { width } maxHeight = { height } primaryButtonText = "Save" secondaryButtonText = "Cancel" primaryButtonOnClick = { ( ) => dashboard . closeModal ( ) } secondaryButtonOnClick = { ( ) => dashboard . closeModal ( ) } title = { title } subtitle = "Edit this file to customize your modal" content = { < Box direction = "vertical" align = "center"
< Text
Wix CLI Modal < / Text
< / Box
} /
< / WixDesignSystemProvider
) ; } ; export default Modal ; 3.
.config.ts - Configurable properties: export default { title : "My Modal" , width : 600 , height : 400 , } ; Then register in src/extensions.ts : import { dashboardmodalYourModal } from './extensions/dashboard/modals/ /extensions.ts' ; export default app ( ) . use ( dashboardmodalYourModal ) // ... other extensions Opening a Modal import { dashboard } from "@wix/dashboard" ; // Simple open const result = await dashboard . openModal ( { modalId : "your-modal-id" , // From .extension.ts id field } ) ; // Pass data to modal via params const result = await dashboard . openModal ( { modalId : "your-modal-id" , params : { userId : user . id , itemData : complexObject , // Objects are passed directly, no encoding needed } , } ) ; // Get notified when the modal is closed const { modalClosed } = dashboard . openModal ( { modalId : "your-modal-id" , } ) ; const result = await modalClosed ; // Resolves with data from closeModal() Receiving Data in Modal Use observeState() to access data passed via params in openModal() : import { dashboard } from "@wix/dashboard" ; import { useEffect , useState } from "react" ; function MyModal ( ) { const [ modalData , setModalData ] = useState < { userId ? : string ; itemData ? : any } ( { } ) ; useEffect ( ( ) => { dashboard . observeState ( ( state ) => { // Access custom data passed through openModal params if ( state . userId ) { setModalData ( { userId : state . userId , itemData : state . itemData , } ) ; } } ) ; } , [ ] ) ; return < div
User ID : { modalData . userId } < / div
; } Closing Modal Call closeModal() from within the modal extension to close it. Optionally pass data back to the opener. import { dashboard } from "@wix/dashboard" ; // Close without returning data dashboard . closeModal ( ) ; // Close with custom return data dashboard . closeModal ( { saved : true , itemId : "123" } ) ; Parameter Type Description closeData Serializable (optional) Data to pass back to the modal opener. Must be cloneable via structured clone algorithm . Supported types: strings, numbers, booleans, plain objects, arrays, Dates, Maps, Sets, ArrayBuffers. Not supported: functions, DOM nodes, class instances with methods, Symbols, Promises. Returns: void Customizing Modal Edit .config.ts for organized settings: export default { title : 'User Settings' , width : 600 , height : 500 , } Import in .tsx : import config from './modal.config.ts' ; export default function MyModal ( ) { return ( < CustomModalLayout title = { config . title } // ... rest of component /
) ; } Common Mistakes Mistake Fix Can't find modal ID Check .extension.ts file's id field Forgetting to register in extensions.ts Import and .use() the modal Using extensionId instead of modalId Use modalId in openModal() Can't access params in modal Use dashboard.observeState() to read passed data Modal won't close Use dashboard.closeModal() from @wix/dashboard Real-World Example // Dashboard Page: Opening edit modal const handleEdit = async ( item : Item ) => { dashboard . openModal ( { modalId : "edit-item-modal-guid" , params : { itemId : item . _id , item : item , // Objects passed directly via params } , } ) ; } ; // Modal: Receiving and saving data export default function ItemEditModal ( ) { const [ formData , setFormData ] = useState < Item | null
( null ) ; useEffect ( ( ) => { dashboard . observeState ( ( state ) => { if ( state . item ) { setFormData ( state . item ) ; } } ) ; } , [ ] ) ; const handleSave = async ( ) => { // Save logic dashboard . showToast ( { message : "Saved!" , type : "success" } ) ; dashboard . closeModal ( ) ; } ; return ( < CustomModalLayout title = "Edit Item" primaryButtonText = "Save" onCloseButtonClick = { ( ) => dashboard . closeModal ( ) } primaryButtonOnClick = { handleSave } content = { / form fields / } /
) ; } Verification After implementation, use wix-cli-app-validation to validate TypeScript compilation, build, preview, and runtime behavior.