# piral-modals

> Plugin for the display of modal dialogs in Piral.

Latest version **1.12.4** (published 2026-09-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install piral-modals
pnpm add piral-modals
yarn add piral-modals
bun add piral-modals
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.12.4 |
| Published | 2026-09-11 |
| First published | 2019-10-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 49.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1932 |
| Author | smapiot |
| Maintainers | florianrappl, manuel.roemer, lschoett |
| Keywords | piral, pilet-api, smapiot, portal, modules, api, plugin, plugin-component, modal, dialog |

## Links

- npm: https://www.npmjs.com/package/piral-modals
- Repository: https://github.com/smapiot/piral
- Homepage: https://piral.io
- Issues: https://github.com/smapiot/piral/issues
- npm.io page: https://npm.io/package/piral-modals

## Alternatives

- [react-native-root-siblings](https://npm.io/package/react-native-root-siblings.md) — 102.9K weekly downloads
- [@praxisui/dialog](https://npm.io/package/@praxisui/dialog.md) — 2.0K weekly downloads
- [easy-toggle-state](https://npm.io/package/easy-toggle-state.md) — 350 weekly downloads
- [ngx-lightbox-evp](https://npm.io/package/ngx-lightbox-evp.md) — 19 weekly downloads
- [react-native-modal-translucent-axton](https://npm.io/package/react-native-modal-translucent-axton.md) — 4 weekly downloads

## Recent versions

- 1.12.4 (latest) — 2026-09-11
- 1.12.4-beta.b76e5ae (next) — 2026-10-21
- 0.15.0-alpha.4409 (canary) — 2022-07-07
- 1.12.4-beta.5c7192f — 2026-10-17
- 1.12.4-beta.ef95646 — 2026-10-17
- 1.12.4-beta.0bc4ce7 — 2026-10-17
- 1.12.4-beta.cf72637 — 2026-10-17
- 1.12.4-beta.92532b1 — 2026-10-16
- 1.12.4-beta.4f77727 — 2026-10-04
- 1.12.4-beta.6cb8b4e — 2026-10-04
- 1.12.4-beta.dc8413a — 2026-10-04
- 1.12.4-beta.80d7277 — 2026-09-29
- 1.12.4-beta.d019a51 — 2026-09-29
- 1.12.4-beta.6c244e5 — 2026-09-09
- 1.12.4-beta.d880426 — 2026-09-09
- … 1138 more at https://npm.io/package/piral-modals/versions

## README

[![Piral Logo](https://github.com/smapiot/piral/raw/main/docs/assets/logo.png)](https://piral.io)

# [Piral Modals](https://piral.io) · [![GitHub License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/smapiot/piral/blob/main/LICENSE) [![npm version](https://img.shields.io/npm/v/piral-modals.svg?style=flat)](https://www.npmjs.com/package/piral-modals) [![tested with vitest](https://img.shields.io/badge/tested_with-vitest-99424f.svg)](https://vitest.dev/) [![Community Chat](https://img.shields.io/discord/1222632475449229352)](https://discord.gg/kKJ2FZmK8t)

This is a plugin that only has a peer dependency to `piral-core`. What `piral-modals` brings to the table is a set of Pilet API extensions that can be used with `piral` or `piral-core` to easily trigger the display of modal dialogs from pilets.

## Why and When

If you have modal dialogs on your page that `piral-modals` gives you a nice abstraction over registering components for them. These items will be stored in the global state container and will be filtered on a given dialog name. Thus the plugin makes only sense if you want to have consistent dialog management.

Alternative: You could simply use an event to trigger opening a dialog. The event could transport a React component which would then be globally used. Alternatively, each pilet would come up with its own dialog design and management system.

## Video

We also have a video for this plugin:

@[youtube](https://youtu.be/gZt7Ic1BHNA)

## Documentation

The following functions are brought to the Pilet API.

### `registerModal()`

Adds a modal dialog definition to the app shell. Can be called from *any* pilet using the specified name.

### `unregisterModal()`

Removes a modal dialog definition from the app shell.

### `showModal()`

Shows the modal dialog registered with the provided name.

Does not open in case no modal dialog using the provided name is available (i.e., registered in the app shell).

## Usage

::: summary: For pilet authors

You can use the `showModal` function from the Pilet API to show a modal dialog registered by any pilet. In case of a naming conflict the dialogs from the current pilet are preferred.

Example use:

```ts
import { PiletApi } from '<name-of-piral-instance>';

export function setup(piral: PiletApi) {
  piral.showModal('my-modal', {
    someValue: 42,
  });
}
```

You can use the `registerModal` function from the Pilet API to add a new modal dialog in the app shell.

Example use:

```ts
import { PiletApi } from '<name-of-piral-instance>';
import { MyModal } from './MyModal';

export function setup(piral: PiletApi) {
  piral.registerModal('my-modal', MyModal);
}
```

You can use the `unregisterModal` function from the Pilet API to remove a previously added modal dialog from the app shell.

Example use:

```ts
import { PiletApi } from '<name-of-piral-instance>';

export function setup(piral: PiletApi) {
  piral.unregisterModal('my-modal');
}
```

:::

::: summary: For Piral instance developers

The provided library only brings API extensions for pilets to a Piral instance.

For the setup of the library itself you'll need to import `createModalsApi` from the `piral-modals` package.

```ts
import { createModalsApi } from 'piral-modals';
```

The integration looks like:

```ts
const instance = createInstance({
  // important part
  plugins: [createModalsApi()],
  // ...
});
```

Via the options the globally available `dialogs` can be defined.

For example:

```ts
const instance = createInstance({
  // important part
  plugins: [createModalsApi({
    dialogs: [
      {
        name: 'userinfo',
        component: UserInfoModal,
      },
    ],
  })],
  // ...
});
```

In order to host the modal dialogs you'll need to embed the `Modals` component somewhere in your layout.

As an example:

```jsx
import { Modals } from 'piral-modals';

const MyLayout = ({ children }) => {
  <div>
    <Modals />
    {children}
  </div>
};
```

If you want to customize the styling (which you should) make sure to register components such as `ModalsHost` (shell for the modals) or `ModalsDialog` (wrapper for an individual dialog) via, e.g., `<SetComponent name="ModalsHost" component={MyModalsHost} />`.

### Customizing

You can customize the available dialogs and their options.

```ts
import type {} from 'piral-modals';

declare module 'piral-modals/lib/types' {
  // interface shared across all dialogs defined in PiralCustomModalsMap
  interface BaseModalOptions {
    common?: boolean;
  }

  interface PiralCustomModalsMap {
    login: {
      required?: boolean;
    };
  }
}

// now showModal("login", { required: true, common: true }) is strongly typed in pilets
```

:::

## License

Piral is released using the MIT license. For more information see the [license file](./LICENSE).

---
_Source: https://npm.io/package/piral-modals · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._