Modal

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

npm install @loomidev/modal lit

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 Esc, or clicking a footer button all dismiss the modal by default. See Non-Dismissible Modal to change that.

Basic modal Please agree to the terms and conditions before proceeding.

<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.

Info Modal We really think you should consider it. What say you? Error Modal You do not have permission to delete this user. Warning Modal This is your first warning. Two more and you're off the platform. Success Modal User deleted successfully.

<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 instead of (or together with) a prebuilt type’s default icon. Modal icons render through <loomi-icon>.

Custom Icon This file is quite large. Continue with the download? Custom Icon + Type This file is quite large. Continue with the download?

<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.

Iconsax Icon This modal's icon comes from the iconsax set.

<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

Tiny I'm the tiniest. Small I'm small. Medium The default size. Large I'm large. XL I'm extra large. Full Width I'm full width.

<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('medium-modal')">Medium</loomi-button>
<loomi-modal size="medium" title="Medium Modal" name="medium-modal">The default size.</loomi-modal>

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

<loomi-button onclick="showLoomiModal('xl-modal')">XL</loomi-button>
<loomi-modal size="xl" title="XL Modal" name="xl-modal">I'm extra large.</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

No Blur The backdrop behind this modal isn't blurred at all. Small Blur A light blur. Medium Blur The default blur. Large Blur A stronger blur. XL Blur A very soft backdrop. OMG Blur The strongest blur preset.

<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('medium-blur')">Medium Blur</loomi-button>
<loomi-modal blur-size="medium" title="Medium Blur" name="medium-blur">The default blur.</loomi-modal>

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

<loomi-button onclick="showLoomiModal('xl-blur')">XL Blur</loomi-button>
<loomi-modal blur-size="xl" title="XL Blur" name="xl-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">.

Custom Labels Rename this file? No Cancel Button I only have an Okay button. No Buttons Only the backdrop or Escape can close me now.

<!-- 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:

Delete User This action cannot be undone.

<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

Left Aligned … Stretched Buttons Each button gets its own full-width row.

<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 Esc from closing it — useful for a “lock screen” or a form that must be explicitly submitted or cancelled.

Lock Screen

Enter your password to continue.

Unlock

<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>

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 Tab 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.

Responsive behavior

For the shared container and viewport rules, see Foundations — Responsive behavior.

Dark mode

For theme activation, token overrides, and contrast guidance, see 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	medium	tiny | small | medium | large | xl | omg
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	medium	none | small | medium | large | xl | omg
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

Open Full Example Are you sure you want to delete this user? This action cannot be undone.

<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="large"
  size="medium"
>
  Are you sure you want to delete this user? This action cannot be undone.
</loomi-modal>

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.

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:

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

Choose your framework

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.

<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>

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.

import "@loomidev/modal";

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.

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

resources/js/app.js

import "@loomidev/modal";

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

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.

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.

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.

<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.

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.

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 {}

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.

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

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

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

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

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.

Dependencies

• @loomidev/button
• @loomidev/core
• @loomidev/icon