@loomidev/notification

<loomi-notification> — a container for stacked, auto-dismissing toasts. Unlike @loomidev/alert, notifications aren't permanently visible — they're triggered from JavaScript and disappear on their own.

npm install @loomidev/notification lit

import "@loomidev/notification";

Basic Usage

Place one <loomi-notification> anywhere on the page — ideally once, in a shared layout, so it's available globally — then trigger toasts from anywhere with showLoomiNotification().

<loomi-button onclick="showLoomiNotification('Saved', 'Your changes were saved.')">Save</loomi-button>

<loomi-notification></loomi-notification>

You don't strictly need to render <loomi-notification> yourself first — showLoomiNotification() creates one (positioned top-right) automatically if none exists on the page yet.

Notification Types

The signature is showLoomiNotification(title, message, type?, dismissIn?, name?). type defaults to "success".

<loomi-button onclick="showLoomiNotification('Delete Successful', 'Your file was deleted.')">Success</loomi-button>
<loomi-button onclick="showLoomiNotification('Delete Failed', 'Could not delete. Try again.', 'error')">Error</loomi-button>
<loomi-button onclick="showLoomiNotification('Low Disk Space', 'You\'ve used 20GB of 25GB.', 'warning')">Warning</loomi-button>
<loomi-button onclick="showLoomiNotification('Invitation Accepted', 'Samuel accepted your invite.', 'info')">Info</loomi-button>

<loomi-notification></loomi-notification>

Multiple Notifications

Trigger as many as you like — they stack, newest on top, each dismissing independently.

<loomi-button onclick="showLoomiNotification('Upload 1 of 3', 'photo-1.jpg uploaded.'); showLoomiNotification('Upload 2 of 3', 'photo-2.jpg uploaded.'); showLoomiNotification('Upload 3 of 3', 'photo-3.jpg uploaded.')">
  Upload 3 Photos
</loomi-button>

<loomi-notification></loomi-notification>

Auto-Dismiss Timing

The fourth argument is seconds before auto-dismiss — default 15. Pass 0 to make a notification persist until the user closes it manually.

<loomi-button onclick="showLoomiNotification('Quick tip', 'This disappears fast.', 'info', 3)">Fast (3s)</loomi-button>
<loomi-button onclick="showLoomiNotification('Read this carefully', 'This stays until dismissed.', 'warning', 0)">Until Dismissed</loomi-button>

<loomi-notification></loomi-notification>

Targeting an Existing Notification

Give a notification a name (the fifth argument) to re-render it in place instead of stacking a duplicate — handy for a repeating error you don't want to spam the user with.

<loomi-button onclick="showLoomiNotification('Upload Failed', 'Network error. Retrying… (1/3)', 'error', 0, 'upload-status')">
  Retry 1
</loomi-button>
<!-- click again with the same `name` — updates the existing toast instead of adding a new one -->
<loomi-button onclick="showLoomiNotification('Upload Failed', 'Network error. Retrying… (2/3)', 'error', 0, 'upload-status')">
  Retry 2
</loomi-button>

<loomi-notification></loomi-notification>

Placement

Use placement to choose where the toast stack anchors. Supported values are top-right, top-center, top-left, bottom-right, bottom-center, and bottom-left. The accent border flips to the opposite side for top-left and bottom-left so it always faces the center of the screen.

<loomi-button onclick="showLoomiNotification('Top Right', 'I render from the top-right corner.')">Notify (top-right)</loomi-button>
<loomi-notification placement="top-right"></loomi-notification>

<loomi-button onclick="showLoomiNotification('Top Center', 'I render centered at the top.')">Notify (top-center)</loomi-button>
<loomi-notification placement="top-center"></loomi-notification>

<loomi-button onclick="showLoomiNotification('Top Left', 'I render from the top-left corner.')">Notify (top-left)</loomi-button>
<loomi-notification placement="top-left"></loomi-notification>

<loomi-button onclick="showLoomiNotification('Bottom Right', 'I render from the bottom-right corner.')">Notify (bottom-right)</loomi-button>
<loomi-notification placement="bottom-right"></loomi-notification>

<loomi-button onclick="showLoomiNotification('Bottom Center', 'I render centered at the bottom.')">Notify (bottom-center)</loomi-button>
<loomi-notification placement="bottom-center"></loomi-notification>

<loomi-button onclick="showLoomiNotification('Bottom Left', 'I render from the bottom-left corner.')">Notify (bottom-left)</loomi-button>
<loomi-notification placement="bottom-left"></loomi-notification>

Full Width

Add full-width to span the entire width of the page instead of floating as a corner card. The banner anchors to the top or bottom edge based on placement — any top-* value anchors top, any bottom-* value anchors bottom.

<loomi-button onclick="showLoomiNotification('Maintenance', 'We\'re deploying in 10 minutes.', 'warning')">Notify</loomi-button>

<loomi-notification placement="top-center" full-width></loomi-notification>

Using the Element Directly

If you already have a reference to the <loomi-notification> element, its notify() method takes the same data as an object — useful if you're rendering it via a framework and want to avoid the global-helper pattern:

document.querySelector("loomi-notification").notify({
  title: "Saved",
  message: "Your changes were saved.",
  type: "success",
  dismissIn: 5,
});

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 | | ------------ | ----------- | ----------------------------------------------------------------------------------------------- | | placement | top-right | top-right | top-center | top-left | bottom-right | bottom-center | bottom-left | | full-width | false | Spans the entire page width, anchored top or bottom per placement. (boolean) |

Helper: showLoomiNotification(title, message, type?, dismissIn?, name?). Method: notify({ title, message, type, dismissIn, name }).

Full Example

<loomi-button
  onclick="showLoomiNotification('Profile Updated', 'Your changes have been saved.', 'success', 8, 'profile-save')"
>
  Save Profile
</loomi-button>

<loomi-notification placement="bottom-right"></loomi-notification>

Framework integration

<loomi-notification> 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/notification unless you are editing LoomiUI itself.

cd /path/to/your-app
npm install @loomidev/notification 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/notification build
pnpm --filter @loomidev/notification 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/[email protected]", "lit/": "https://esm.sh/[email protected]/" } }
</script>
<script type="module" src="https://esm.sh/@loomidev/notification"></script>

<loomi-notification placement="top-right"></loomi-notification>

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/notification";

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/notification lit
npm run dev

// resources/js/app.js
import "@loomidev/notification";

<loomi-notification placement="top-right"></loomi-notification>

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/notification";

export function LoomiExample() {
  return (
    <loomi-notification placement="top-right"></loomi-notification>
  );
}

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/notification";
</script>

<template>
  <loomi-notification placement="top-right"></loomi-notification>
</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/notification";

@Component({
  selector: "app-root",
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <loomi-notification placement="top-right"></loomi-notification>
  `,
})
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/notification";
</script>

<loomi-notification placement="top-right"></loomi-notification>

---
import "@loomidev/notification";
---

<loomi-notification placement="top-right"></loomi-notification>

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/core
• @loomidev/icon