Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Frontend Modules

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

# Dashboard Modal Extension Files and Code

When you add a [dashboard modal](fallback::https://dev.wix.com/docs/overview/extensions-framework/dashboard-extensions/dashboard-modals) extension, the generated files land under `src/extensions/dashboard/modals/<modal-folder>/` and the extension is registered in your project's `extensions.ts`.

This file set is the same whether you add the modal in a Studio Two site project or in a Wix CLI project.

```text
src/
└── extensions/
    └── dashboard/
        └── modals/
            └── <modal-folder>/
                ├── <modal-folder>.extension.ts
                ├── <modal-folder>.config.ts
                └── <modal-folder>.tsx
```

| File | What it's for |
|------|---------------|
| `<modal-folder>.extension.ts` | The [configuration file](fallback::#configuration-file) for the modal ID, title, size, and component path. |
| `<modal-folder>.config.ts` | The [shared config](fallback::#shared-config) for title, width, and height. |
| `<modal-folder>.tsx` | The [modal content](fallback::#modal-content): the React component that renders when the modal is open. |

## Configuration file

The `<modal-folder>.extension.ts` file declares the modal with `extensions.dashboardModal()`.

Import `extensions` from the package your project uses:

```ts
// Studio Two site
import { extensions } from '@wix/custom-extensions';
```

```ts
// Wix CLI app or headless project
import { extensions } from '@wix/astro/builders';
```

```ts
export default extensions.dashboardModal({
  id: string,
  title: string,
  width: number,
  height: number,
  component: string,
});
```

Example:

```ts
import config from './my-custom-modal.config';

export default extensions.dashboardModal({
  id: '881eedb6-b5a1-4b86-ac13-72c73df1af4a',
  title: config.title,
  width: config.width,
  height: config.height,
  component: './extensions/dashboard/modals/my-custom-modal/my-custom-modal.tsx',
});
```

### Configuration fields

| Field | Type | Description |
|--|--|--|
| `id` | string | Modal ID as a GUID. Used to register the modal, and as the `modalId` you pass to [`openModal()`](fallback::https://dev.wix.com/docs/sdk/host-modules/dashboard/open-modal). It must be unique across all dashboard modals in the project. When the modal belongs to an app, this ID is also how the modal is registered in the [app dashboard](fallback::https://manage.wix.com/account/custom-apps). |
| `title` | string | The modal title. Used to refer to the modal in the project dashboard. |
| `width` | number | Initial width of the modal while loading. |
| `height` | number | Initial height of the modal while loading. |
| `component` | string | Path to the modal content component. |

## Shared config

The `<modal-folder>.config.ts` file holds title, width, and height together. The configuration file and the React component both import it.

```ts
export default {
  title: 'My Custom Modal',
  width: 550,
  height: 600,
};
```

Change these values when you want a different title or a different size. Keep the modal ID stable once other code depends on it. Dashboard pages and menu plugins use this value as the target modal ID.

## Modal content

The `<modal-folder>.tsx` file exports a React component that renders when the modal is open.

A generated modal typically wraps its content in `WixDesignSystemProvider` and `CustomModalLayout`. Inside a dashboard modal component you can use:

- The [Dashboard SDK](fallback::https://dev.wix.com/docs/sdk/host-modules/dashboard/introduction) to close the modal, open other modals, navigate between dashboard locations, and show toasts.
- The [Wix Design System](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/design/about-the-wix-design-system) to display content using the same React components Wix uses to build its own dashboard pages.
- The [Wix JavaScript SDK](fallback::https://dev.wix.com/docs/sdk) to access and manage Wix data.

To receive custom data passed by `openModal()` or by a menu plugin that opens the modal, call [`observeState()`](fallback::https://dev.wix.com/docs/sdk/host-modules/dashboard/observe-state).

## See also

- [About Dashboard Modals](fallback::https://dev.wix.com/docs/dashboard-extensions/dashboard-modals/about-dashboard-modals)
- [Dashboard Modals](fallback::https://dev.wix.com/docs/overview/extensions-framework/dashboard-extensions/dashboard-modals)
- [`openModal()`](fallback::https://dev.wix.com/docs/sdk/host-modules/dashboard/open-modal)
- [`closeModal()`](fallback::https://dev.wix.com/docs/sdk/host-modules/dashboard/close-modal)
- [`observeState()`](fallback::https://dev.wix.com/docs/sdk/host-modules/dashboard/observe-state)

File	What it's for
`<modal-folder>.extension.ts`	The configuration file for the modal ID, title, size, and component path.
`<modal-folder>.config.ts`	The shared config for title, width, and height.
`<modal-folder>.tsx`	The modal content: the React component that renders when the modal is open.