# @loomidev/modal

`<loomi-modal>` - an overlay dialog with types, sizes, and action buttons.

```bash
npm install @loomidev/modal lit
```

```js
import "@loomidev/modal";
```

## Default Modal

Modals are usually triggered by an action - a button click, say. Every LoomiUI modal is
opened and closed by its unique `name`, using the exported `showLoomiModal()` /
`hideLoomiModal()` helpers (or the instance methods `show()`/`hide()` if you already
have a reference to the element).

> **Important:** give every modal on a page a unique `name` - it's how `showLoomiModal()`
> finds the right one.

The default modal keeps its content left aligned and places action buttons in a gray
footer, right aligned. Clicking the backdrop, pressing <kbd>Esc</kbd>, or clicking a
footer button all dismiss the modal by default. See
[Non-Dismissible Modal](#non-dismissible-modal) to change that.

```html
<loomi-button onclick="showLoomiModal('tnc-agreement')">Basic modal</loomi-button>

<loomi-modal name="tnc-agreement" title="Agree or Disagree">
  Please agree to the terms and conditions before proceeding.
</loomi-modal>

<script type="module">
  import { showLoomiModal } from "@loomidev/modal";
</script>
```

## Different Types

Four prebuilt types add a left-side icon and matching action color. The default (no
`type` set) has no icon.

```html
<loomi-button onclick="showLoomiModal('info')">Info Modal</loomi-button>
<loomi-modal type="info" title="General Info" name="info">
  We really think you should consider it. What say you?
</loomi-modal>

<loomi-button onclick="showLoomiModal('error')">Error Modal</loomi-button>
<loomi-modal type="error" title="Delete Not Allowed" name="error">
  You do not have permission to delete this user.
</loomi-modal>

<loomi-button onclick="showLoomiModal('warning')">Warning Modal</loomi-button>
<loomi-modal type="warning" title="First Warning" name="warning">
  This is your first warning. Two more and you're off the platform.
</loomi-modal>

<loomi-button onclick="showLoomiModal('success')">Success Modal</loomi-button>
<loomi-modal type="success" title="User Deleted" name="success">
  User deleted successfully.
</loomi-modal>
```

## Using Different Icons

Set `icon` to use any icon from [`@loomidev/icons`](../icons) instead of (or together with)
a prebuilt `type`'s default icon. Modal icons render through `<loomi-icon>`.

```html
<loomi-button onclick="showLoomiModal('big-file')">Custom Icon</loomi-button>
<loomi-modal icon="cloud-arrow-down" title="Large File Size" name="big-file">
  This file is quite large. Continue with the download?
</loomi-modal>

<!-- combine a custom icon with a predefined color -->
<loomi-button onclick="showLoomiModal('big-file-warn')">Custom Icon + Type</loomi-button>
<loomi-modal type="warning" icon="cloud-arrow-down" title="Large File Size" name="big-file-warn">
  This file is quite large. Continue with the download?
</loomi-modal>
```

### Icon Source

`icon` renders from `heroicons` by default. Set `icon-source` to pull from a different
set instead - `iconsax` or `untitledui` - matching `<loomi-icon>`'s own `source` attribute.
Those sets are opt-in: import each one you use once, with `import "@loomidev/icons/iconsax";`.

```html
<loomi-button onclick="showLoomiModal('iconsax-modal')">Iconsax Icon</loomi-button>
<loomi-modal icon="home" icon-source="iconsax" title="Iconsax Icon" name="iconsax-modal">
  This modal's icon comes from the iconsax set.
</loomi-modal>
```

## Different Sizes

```html
<loomi-button onclick="showLoomiModal('tiny-modal')">Tiny</loomi-button>
<loomi-modal size="tiny" title="Tiny Modal" name="tiny-modal">I'm the tiniest.</loomi-modal>

<loomi-button onclick="showLoomiModal('small-modal')">Small</loomi-button>
<loomi-modal size="small" title="Small Modal" name="small-modal">I'm small.</loomi-modal>

<loomi-button onclick="showLoomiModal('regular-modal')">Regular</loomi-button>
<loomi-modal size="regular" title="Regular Modal" name="regular-modal">The default size.</loomi-modal>

<loomi-button onclick="showLoomiModal('big-modal')">Big</loomi-button>
<loomi-modal size="big" title="Big Modal" name="big-modal">I'm big.</loomi-modal>

<loomi-button onclick="showLoomiModal('huge-modal')">Huge</loomi-button>
<loomi-modal size="huge" title="Huge Modal" name="huge-modal">I'm huge.</loomi-modal>

<loomi-button onclick="showLoomiModal('omg-modal')">Full Width</loomi-button>
<loomi-modal size="omg" title="Full Width Modal" name="omg-modal">I'm full width.</loomi-modal>
```

## Backdrop Blur Intensity

```html
<loomi-button onclick="showLoomiModal('no-blur')">No Blur</loomi-button>
<loomi-modal blur-size="none" title="See Through Me" name="no-blur">
  The backdrop behind this modal isn't blurred at all.
</loomi-modal>

<loomi-button onclick="showLoomiModal('small-blur')">Small Blur</loomi-button>
<loomi-modal blur-size="small" title="Small Blur" name="small-blur">A light blur.</loomi-modal>

<loomi-button onclick="showLoomiModal('regular-blur')">Regular Blur</loomi-button>
<loomi-modal blur-size="regular" title="Regular Blur" name="regular-blur">The default blur.</loomi-modal>

<loomi-button onclick="showLoomiModal('big-blur')">Big Blur</loomi-button>
<loomi-modal blur-size="big" title="Big Blur" name="big-blur">A stronger blur.</loomi-modal>

<loomi-button onclick="showLoomiModal('huge-blur')">Huge Blur</loomi-button>
<loomi-modal blur-size="huge" title="Huge Blur" name="huge-blur">A very soft backdrop.</loomi-modal>

<loomi-button onclick="showLoomiModal('omg-blur')">OMG Blur</loomi-button>
<loomi-modal blur-size="omg" title="OMG Blur" name="omg-blur">The strongest blur preset.</loomi-modal>
```

Available: `none` `small` `medium` `large` `xl` `omg`.

## Action Buttons

By default the footer shows `Cancel` and `Okay`. Customize the labels, or set a label to
an empty string to hide that button entirely. Footer actions render as
`<loomi-button size="small">`.

```html
<!-- custom labels -->
<loomi-button onclick="showLoomiModal('rename')">Custom Labels</loomi-button>
<loomi-modal name="rename" ok-button-label="Rename" cancel-button-label="Not now">
  Rename this file?
</loomi-modal>

<!-- no cancel button -->
<loomi-button onclick="showLoomiModal('no-cancel')">No Cancel Button</loomi-button>
<loomi-modal name="no-cancel" cancel-button-label="">I only have an Okay button.</loomi-modal>

<!-- no buttons at all (e.g. you have your own submit button inside the modal) -->
<loomi-button onclick="showLoomiModal('no-buttons')">No Buttons</loomi-button>
<loomi-modal name="no-buttons" show-action-buttons="false">
  Only the backdrop or Escape can close me now.
</loomi-modal>
```

### Reacting to Action Buttons

Loomi modals fire real DOM events - listen for `ok`/`cancel` on the modal element:

```html
<loomi-button onclick="showLoomiModal('confirm-delete')">Delete User</loomi-button>
<loomi-modal name="confirm-delete" type="warning" title="Delete user?"
  ok-button-label="Yes, delete" cancel-button-label="Keep it" close-after-action="false">
  This action cannot be undone.
</loomi-modal>

<script type="module">
  const modal = document.querySelector('loomi-modal[name="confirm-delete"]');
  modal.addEventListener("ok", () => {
    deleteUser().then(() => modal.hide());
  });
  modal.addEventListener("cancel", () => console.log("kept the user"));
</script>
```

`close-after-action="false"` keeps the modal open after a button click - useful when the
action is asynchronous and you want to close it yourself once it resolves (as above).

### Alignment & Stretching

```html
<loomi-button onclick="showLoomiModal('left-aligned')">Left Aligned</loomi-button>
<loomi-modal name="left-aligned" align-buttons="left" title="Left Aligned">…</loomi-modal>

<loomi-button onclick="showLoomiModal('stretched')">Stretched Buttons</loomi-button>
<loomi-modal name="stretched" stretch-action-buttons title="Stretched">
  Each button gets its own full-width row.
</loomi-modal>
```

## Non-Dismissible Modal

Set `backdrop-can-close="false"` to stop the backdrop and <kbd>Esc</kbd> from closing
it - useful for a "lock screen" or a form that must be explicitly submitted or
cancelled.

```html
<loomi-button onclick="showLoomiModal('lock-screen')">Lock Screen</loomi-button>
<loomi-modal name="lock-screen" backdrop-can-close="false" show-action-buttons="false">
  <p>Enter your password to continue.</p>
  <loomi-input type="password" label="Password"></loomi-input>
  <loomi-button block onclick="hideLoomiModal('lock-screen')">Unlock</loomi-button>
</loomi-modal>
```

## Confirm dialogs

`loomiConfirm()` is the LoomiUI counterpart to `window.confirm()`: it returns a promise
that resolves `true` only when OK is clicked. Cancel, <kbd>Escape</kbd>, a backdrop click
and the close icon all resolve `false`. It's also available as `window.loomiConfirm`.

```html
<form id="reset-pin">
  <loomi-button type="submit">Reset PIN</loomi-button>
</form>
<loomi-button id="delete-btn" color="error">Delete project</loomi-button>

<script type="module">
  import { loomiConfirm } from "@loomidev/modal";

  // Guard a form submit: stop it, ask, then submit for real.
  const form = document.getElementById("reset-pin");
  form.addEventListener("submit", async (event) => {
    event.preventDefault();
    const ok = await loomiConfirm("Reset this PIN?", {
      body: "They'll be signed out of every device.",
      okLabel: "Yes, continue",
    });
    if (ok) form.submit(); // form.submit() skips the submit event, so no loop
  });

  // Guard a destructive button.
  document.getElementById("delete-btn").addEventListener("click", async () => {
    if (await loomiConfirm("Delete this project?", { type: "error", okLabel: "Delete" })) {
      deleteProject();
    }
  });
</script>
```

| Option        | Default     | Description                                          |
| ------------- | ----------- | ---------------------------------------------------- |
| `body`        | -           | Secondary text under the message.                    |
| `type`        | `'warning'` | `''` \| `info` \| `error` \| `warning` \| `success`. |
| `okLabel`     | localised   | OK button label (defaults from i18n).                |
| `cancelLabel` | localised   | Cancel button label (defaults from i18n).            |
| `size`        | `'small'`   | Dialog width, same scale as the `size` attribute.    |

- The message and `body` are set as plain text, never parsed as HTML, so user-supplied
  strings are safe to pass.
- One `<loomi-modal>` is reused for every call. A call made while a dialog is open is
  **queued**, not rejected: it appears after the current one is dismissed, in call order,
  and every promise resolves with its own answer.
- Focus moves into the dialog and returns to the trigger afterwards, same as any modal.
- Plain DOM and a native `Promise` only - no framework hooks. Wire it into your framework's
  own event handlers.

## Focus Handling

Opening a modal moves focus into it (the close icon if shown, otherwise the first
focusable element, otherwise the dialog itself) and traps <kbd>Tab</kbd> inside it while
open. Closing it restores focus to whatever was focused before - all automatic, no setup
needed.

## Opening and closing motion

The backdrop fades in and the dialog rises into place; closing plays both in reverse
rather than making the modal vanish. `prefers-reduced-motion: reduce` shortens every
loomi animation to near-zero, so the modal appears and disappears at once for readers who
ask for that.

Everything observable happens as soon as `hide()` is called - `open` flips to `false`, the
`close` event fires, focus returns to whatever had it, and the page scroll lock is
released. Only the visuals wait for the animation, which also means the element returns
from `document.body` to its original position in the DOM when the exit finishes rather
than immediately (moving a node cancels the animation running on it). If you need the old
instant behavior, set `open = false` directly instead of calling `hide()`.

## Accessibility

For the library-wide baseline, see [Foundations - Accessibility](https://loomiui.com/foundations/#accessibility).

## Responsive behavior

For the shared container and viewport rules, see [Foundations - Responsive behavior](https://loomiui.com/foundations/#responsive-behavior).

## Dark mode

For theme activation, token overrides, and contrast guidance, see [Foundations - Dark mode](https://loomiui.com/foundations/#dark-mode).

## Attributes

| Attribute                | Default     | Description                                                                                                                                             |
| ------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                   | _(blank)_   | Unique name for `showLoomiModal()` / `hideLoomiModal()`.                                                                                                |
| `title`                  | _(blank)_   | Modal heading.                                                                                                                                          |
| `type`                   | _(blank)_   | `info` \| `error` \| `warning` \| `success` (sets icon + color).                                                                                        |
| `icon`                   | _(blank)_   | Custom icon name (overrides the type icon).                                                                                                             |
| `icon-source`            | `heroicons` | Icon set for `icon` - `heroicons` \| `iconsax` \| `untitledui`.                                                                                         |
| `size`                   | `regular`   | `tiny` \| `small` \| `regular` \| `big` \| `huge` \| `omg`. See [Sizing](https://github.com/loomidev/loomiui/blob/main/packages/core/README.md#sizing). |
| `open`                   | `false`     | Open state (reflected). _(boolean)_                                                                                                                     |
| `ok-button-label`        | `Okay`      | Primary button text (blank hides it).                                                                                                                   |
| `cancel-button-label`    | `Cancel`    | Secondary button text (blank hides it).                                                                                                                 |
| `show-action-buttons`    | `true`      | Show the footer buttons. _(boolean)_                                                                                                                    |
| `show-close-icon`        | `false`     | Show the top-right close icon. _(boolean)_                                                                                                              |
| `backdrop-can-close`     | `true`      | Backdrop click / Escape closes. _(boolean)_                                                                                                             |
| `close-after-action`     | `true`      | Close after an action button is clicked. _(boolean)_                                                                                                    |
| `prevent-scroll`         | `true`      | Prevent document scrolling while open. _(boolean)_                                                                                                      |
| `blur-size`              | `regular`   | `none` \| `small` \| `regular` \| `big` \| `huge` \| `omg`. See [Sizing](https://github.com/loomidev/loomiui/blob/main/packages/core/README.md#sizing). |
| `align-buttons`          | `right`     | `left` \| `center` \| `right`                                                                                                                           |
| `stretch-action-buttons` | `false`     | Full-width stacked buttons. _(boolean)_                                                                                                                 |

Boolean attributes can be omitted, present, or set to `"false"` in HTML, for example
`backdrop-can-close="false"` or `show-close-icon`.

**Methods:** `show()`, `hide()`. **Helpers:** `showLoomiModal(name)`, `hideLoomiModal(name)`.

## Slots

| Slot        | Description                          |
| ----------- | ------------------------------------ |
| _(default)_ | Content placed inside the component. |

## Events

| Event    | Description                                 |
| -------- | ------------------------------------------- |
| `cancel` | Fired when the cancel action is activated.  |
| `close`  | Fired when the component closes.            |
| `ok`     | Fired when the confirm action is activated. |
| `open`   | Fired when the component opens.             |

## Full Example

```html
<loomi-button onclick="showLoomiModal('full-modal')">Open Full Example</loomi-button>
<loomi-modal
  type="warning"
  title="Confirm deletion"
  name="full-modal"
  ok-button-label="Yes, delete"
  cancel-button-label="Keep it"
  close-after-action="false"
  backdrop-can-close="false"
  show-close-icon="true"
  blur-size="big"
  size="regular"
>
  Are you sure you want to delete this user? This action cannot be undone.
</loomi-modal>
```

<!-- BEGIN loomi-framework-guide -->

## Framework integration

`<loomi-modal>` is a standard custom element, so the browser can use it in plain HTML, Blade, React, Vue, Angular, Svelte, Astro, and most other frameworks. The important beginner rule is: install the package, import it once before the tag is rendered, then write the Loomi tag in your template.

### Where to run commands

Run install commands from the app where you want to use this component. That means the folder that contains that app's `package.json`. Do not run these install commands from `packages/modal` unless you are editing LoomiUI itself.

```bash
cd /path/to/your-app
npm install @loomidev/modal lit
```

If you are contributing to LoomiUI itself, first move to the top-level `components` folder. That is where the main `package.json` for all packages lives, and `pnpm --filter ...` commands should be run from there:

```bash
cd /path/to/your-copy-of-loomiui/components
pnpm --filter @loomidev/modal build
pnpm --filter @loomidev/modal typecheck
```

### Choose your framework

<loomi-tabs>
<loomi-tab label="HTML" active>

Use the CDN version for prototypes, documentation pages, or a quick reproduction. The import map tells the browser where to find Lit, which Loomi components use internally.

```html
<script type="importmap">
  { "imports": { "lit": "https://esm.sh/lit@3.3.3", "lit/": "https://esm.sh/lit@3.3.3/" } }
</script>
<script type="module" src="https://esm.sh/@loomidev/modal"></script>

<loomi-modal name="confirm-delete" title="Delete customer?" type="warning">
  This action cannot be undone.
</loomi-modal>
```

</loomi-tab>
<loomi-tab label="Bundlers and SPAs">

In Vite, Webpack, Parcel, Rollup, or a framework build pipeline, install the package and import it once in your main app JavaScript file. After that, you can use the Loomi tag anywhere in your app.

```js
import "@loomidev/modal";
```

</loomi-tab>
<loomi-tab label="Blade">

Run the install command from your Laravel project root, then import the component in `resources/js/app.js`. If your project uses Laravel Vite, `npm run dev` and `npm run build` should also be run from the Laravel project root.

```bash
cd /path/to/your-laravel-app
npm install @loomidev/modal lit
npm run dev
```

```js
// resources/js/app.js
import "@loomidev/modal";
```

```blade
<loomi-modal name="confirm-delete" title="Delete customer?" type="warning">
  This action cannot be undone.
</loomi-modal>
```

</loomi-tab>
<loomi-tab label="React">

React can render Loomi tags directly. If you are on React 18, or if you need to pass arrays, objects, or functions, use a ref and assign those values after the component mounts.

```jsx
import "@loomidev/modal";

export function LoomiExample() {
  return (
    <loomi-modal name="confirm-delete" title="Delete customer?" type="warning">
      This action cannot be undone.
    </loomi-modal>
  );
}
```

If TypeScript does not recognize the Loomi tag in JSX, add it to your app's JSX type declarations.

</loomi-tab>
<loomi-tab label="Vue">

Import the package in the component that uses it, or once in your main Vue file. Vue templates can use Loomi tags directly. For arrays, objects, or functions, pass the value as a JavaScript property instead of as plain text.

```vue
<script setup>
import "@loomidev/modal";
</script>

<template>
  <loomi-modal name="confirm-delete" title="Delete customer?" type="warning">
    This action cannot be undone.
  </loomi-modal>
</template>
```

If Vue warns that the tag is an unknown component, configure `compilerOptions.isCustomElement` for tags that start with `loomi-` in your Vite or Vue config.

</loomi-tab>
<loomi-tab label="Angular">

Import the package once and tell Angular to allow custom HTML tags with `CUSTOM_ELEMENTS_SCHEMA`. For NgModule apps, add the schema to the module instead of the standalone component.

```ts
// app.component.ts
import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
import "@loomidev/modal";

@Component({
  selector: "app-root",
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <loomi-modal name="confirm-delete" title="Delete customer?" type="warning">
      This action cannot be undone.
    </loomi-modal>
  `,
})
export class AppComponent {}
```

</loomi-tab>
<loomi-tab label="Svelte / Astro">

Svelte can import the package inside a component script. Astro can import it in the frontmatter of the page or layout where the tag appears.

```svelte
<script>
  import "@loomidev/modal";
</script>

<loomi-modal name="confirm-delete" title="Delete customer?" type="warning">
  This action cannot be undone.
</loomi-modal>
```

```astro
---
import "@loomidev/modal";
---

<loomi-modal name="confirm-delete" title="Delete customer?" type="warning">
  This action cannot be undone.
</loomi-modal>
```

</loomi-tab>
</loomi-tabs>

### Server-side rendering notes

Frameworks such as Next.js, Nuxt, SvelteKit, and Astro sometimes render HTML on the server before browser-only code runs. If your framework complains, move the Loomi import to client-side code. In Next.js, that usually means a component with `"use client"`; in Nuxt, it often means a `.client.ts` plugin.

<!-- END loomi-framework-guide -->

<!-- bundle-size:start -->

## Bundle size

About **27.8 KB** minified and gzipped, including its styles and the shared `@loomidev/core` and `@loomidev/theme` code, and excluding `lit`. Icons load one at a time, on first use, and aren't included. Importing `@loomidev/icons/all` to load every Heroicon up front makes it 100.8 KB. Measured by `pnpm check:bundle-size`.

<!-- bundle-size:end -->

## Dependencies

- `@loomidev/button`
- `@loomidev/core`
- `@loomidev/icon`