@loomidev/empty-state

<loomi-empty-state> — a friendly placeholder for empty content, so users see a helpful message instead of a boring blank page. Comes with a built-in illustration, but is intentionally minimal so different apps can shape it to their needs.

npm install @loomidev/empty-state lit

import "@loomidev/empty-state";

Basic Usage

<loomi-empty-state
  message="Awesome! You have no documents to approve."
  button-label="Go to Dashboard"
></loomi-empty-state>

Custom Image

<loomi-empty-state
  message="You haven't saved any gists yet."
  image="/illustrations/no-code.svg"
  button-label="Create Gist"
></loomi-empty-state>

With a Heading

<loomi-empty-state
  heading="Create gists already"
  message="You haven't saved any gists yet."
  image="/illustrations/no-code.svg"
  button-label="Create Gist"
></loomi-empty-state>

Reacting to the Action Button

document.querySelector("loomi-empty-state").addEventListener("action", () => {
  router.push("/gists/new");
});

Without a Call to Action

Omit button-label to show a message with no action button — appropriate when there's nothing for the user to actively do yet.

<loomi-card title="Recent Activity">
  <loomi-empty-state
    image="/illustrations/no-activity.svg"
    message="Your recent activity will show up here once your team gets moving."
  ></loomi-empty-state>
</loomi-card>

Custom Content (No Illustration)

Set show-image="false" to take full control via the default slot instead of the built-in image/heading/message/button layout.

<loomi-empty-state show-image="false">
  <loomi-icon name="finger-print" style="width: 3rem; height: 3rem"></loomi-icon>
  <p>You have no biometric data available</p>
  <loomi-button color="error" size="small">Add biometric info</loomi-button>
</loomi-empty-state>

Image Sizes

<loomi-empty-state message="Small" image-size="small"></loomi-empty-state>
<loomi-empty-state message="Large" image-size="large"></loomi-empty-state>
<loomi-empty-state message="Extra large" image-size="xl"></loomi-empty-state>

Using It Inside <loomi-select> and <loomi-table>

<loomi-select> and <loomi-table> currently render their own plain-text empty states rather than a full <loomi-empty-state> — see those packages' READMEs for their respective empty-placeholder / no-data-message attributes. Use <loomi-empty-state> directly wherever you need the richer illustration + CTA version.

Replacing the Built-in Illustration

The default illustration (shown whenever image is left blank) is a PNG bundled with the package and inlined as a data URI at build time, so it works the same whether the package is loaded from npm, a bundler, or a CDN — no extra network request and no asset-path resolution for consumers to configure.

If you're contributing to LoomiUI itself and want to change it, replace src/assets/default-image.png with a same-named PNG and rebuild:

cd /path/to/your-copy-of-loomiui/components
pnpm --filter @loomidev/empty-state build

scripts/build-assets.mjs re-encodes whatever PNG is at that path into src/generated/default-image.ts on every build — no code changes needed.

Accessibility

• Decorative illustration is hidden from assistive tech; action button is a native <button>.

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 | | -------------- | --------- | --------------------------------------------------------------- | | heading | (blank) | Optional heading. | | message | (blank) | Main message text. | | button-label | (blank) | Action button text (omit to hide). | | image | (blank) | Custom image URL (defaults to a built-in illustration). | | image-size | medium | small | medium | large | xl | omg | | show-image | true | Show the illustration. Set false to use the slot. (boolean) |

Slots

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

Events

| Event | Description | | -------- | ------------------------------------------------------- | | action | Fired when the component's primary action is activated. |

Full Example

<loomi-empty-state
  heading="Nothing to see here"
  message="Hey! You've cleaned up your inbox nicely."
  button-label="Compose a message"
  image="/illustrations/empty-inbox.png"
  image-size="xl"
></loomi-empty-state>

Framework integration

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

cd /path/to/your-app
npm install @loomidev/empty-state 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/empty-state build
pnpm --filter @loomidev/empty-state 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/empty-state"></script>

<loomi-empty-state
  heading="No invoices"
  message="Invoices will appear here after the first payment."
  button-label="Create invoice"
></loomi-empty-state>

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/empty-state";

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

// resources/js/app.js
import "@loomidev/empty-state";

<loomi-empty-state
  heading="No invoices"
  message="Invoices will appear here after the first payment."
  button-label="Create invoice"
></loomi-empty-state>

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/empty-state";

export function LoomiExample() {
  return (
    <loomi-empty-state
      heading="No invoices"
      message="Invoices will appear here after the first payment."
      button-label="Create invoice"
    ></loomi-empty-state>
  );
}

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

<template>
  <loomi-empty-state
    heading="No invoices"
    message="Invoices will appear here after the first payment."
    button-label="Create invoice"
  ></loomi-empty-state>
</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/empty-state";

@Component({
  selector: "app-root",
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <loomi-empty-state
      heading="No invoices"
      message="Invoices will appear here after the first payment."
      button-label="Create invoice"
    ></loomi-empty-state>
  `,
})
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/empty-state";
</script>

<loomi-empty-state
  heading="No invoices"
  message="Invoices will appear here after the first payment."
  button-label="Create invoice"
></loomi-empty-state>

---
import "@loomidev/empty-state";
---

<loomi-empty-state
  heading="No invoices"
  message="Invoices will appear here after the first payment."
  button-label="Create invoice"
></loomi-empty-state>

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