> For the complete documentation index, see [llms.txt](https://docs.navigaglobal.com/dashboard-plugin/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.navigaglobal.com/dashboard-plugin/api-and-gui/api/openmodal.md).

# openModal

## How to use

openModal method takes an object as an argument. This object should contain at least the component key which should point to your Modal component. You could also add a props key pointing to an objecting containing extra properties that will be passed down the modal component.

```jsx
import { Plugin } from '@root'
import MyModal from '@components/MyModal'

const App = () => {
    const handleOpenMyModal = useCallback(() => {
        Plugin.openModal({
            component: MyModal,
            props: {
                // pass down custom props to MyModal component
            }
        })
    }, [])
    
    return (
        <div>
            <button onClick={handleOpenMyModal}>
                {'Open my modal'}
            </button>
        </div>
    )
}
```

### Properties

| Name                | typeof                                           | default   | Description                                                                                 |
| ------------------- | ------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------- |
| size                | String                                           | NORMAL    | The size of your modal, check out available sizes below                                     |
| menu                | Component \|\| Node                              | null      | A custom component to be rendered in the header of the modal                                |
| title               | String                                           | undefined | A title for the modal to be displayed in the header                                         |
| customStyle         | String \|\| Object \|\| Styled-Component's style | undefined | Custom css style for the modal                                                              |
| withHeader          | Boolean                                          | true      | A flag if Dashboard should render a header with a close icon                                |
| closeOnClickOutside | Boolean                                          | false     | A flag if Dashboard should close the modal if a click happened outside of the modal context |

### Sizes

Dashboard comes with a range of predefined sizes you'll be able to choose from in order to render your modal.&#x20;

Choose your size by first retrieve the available ones form the PluginAPI

```jsx
import { Plugin } from '@root'

const modalSizes = Plugin.MODALSIZE
```

| Name   | size                                                             |
| ------ | ---------------------------------------------------------------- |
| AUTO   | Depends on your modal actual size, `width: unset, height: unset` |
| NORMAL | `max-height: 93%, max-width: 1024px`                             |
| WIDE   | `max-width: 85%, max-height: 93%`                                |
| FULL   | `max-width: 100%, max-height: 100%`                              |

## Multiple modals

Before Dashboard 4.1, modals used to be rendered by calling Plugin.modal.open(...)\
And that allowed the plugins to render one modal at a time, but with the new ModalAPI, Dashboard supports opening multiple modals at the same time without un-mounting the previous ones.

For example, if you call the deprecated method Plugin.modal.open(...) while you have a modal already rendered, Dashboard will un-mount the rendered modal, and mount the new one. When them a user closes the modal, Dashboard will close the current opened one without going back to the previous one

With the new API Dashboard will stack the modals on top of each other every time Plugin.openModal(...) has been called<br>

So to open multiple modals, simply call Plugin.openModal(...) with your new modal properties

## Confirm before close

You can tell Dashboard to display a confirm prompt to the user, when the user tries to close your modal\
This could be appropriate to do if your modal has changes that will get lost, or still processing some data.

Dashboard will look into your modal component ref and check if the ref has a`onBeforeClose()` method.\
If so Dashboard will call the method and wait for it to resolve or reject, therefore it should return a promise.

If onBeforeClose() resolves then Dashboard will close the modal right away.\
If it's rejected, Dashboard will display a dialog to the user to confirm closing the modal, or cancel.

You can specify the dialog message along with the dialog button labels.\
You also can register callbacks to see what action the user took, onConfirm/onCancel

{% hint style="info" %}
The object you reject with, will be the dialog params
{% endhint %}

**Dialog params**

| Param         |  Typeof  | Required | Description                                                                                  |
| ------------- | :------: | :------: | -------------------------------------------------------------------------------------------- |
| message       |  String  |    \*    | A message to be displayed to the user within the dialog                                      |
| localizations |  Object  |          | Button labels localization strings                                                           |
| onCancel      | Function |          | On cancel callback will be called when the user clicks on Cancel button or closes the dialog |
| onConfirm     | Function |          | On confirm callback will be called when the user clicks on Confirm button                    |

**Example**

```jsx
import {
    Plugin
} from '@root'

import {
    useRef,
    forwardRef,
    useImperativeHandle
} from 'react'

const MyModal = (props, ref) => {
    const hasChanges = useRef()
    
    useImperativeHandle(ref, () => ({
        onBeforeClose: () => {
            return new Promise((resolve, reject) => {
                if (hasChanges.current) {
                    reject({
                        message: 'Are you sure you want to cancel?'
                        localizations: {
                            cancel: 'Continue editing',
                            confirm: 'Discard my changes'
                        },
                        onCancel: () => {},
                        onConfirm: () => {}
                    })
                } else {
                    resolve()
                }
            })
        }
    }))
    
    return (
        <div>
            <p>{'My awesome modal'}</p>
        </div>
    )
}

export default forwardRef(MyModal)
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.navigaglobal.com/dashboard-plugin/api-and-gui/api/openmodal.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.