Button

<loomi-button> — a themeable, framework-agnostic button web component built with Lit.

The button renders as an HTML <button> by default. Its look is controlled with separate, easy-to-combine attributes: type controls the style, color controls the palette, and size, radius, outline, and border-width adjust the details. This is easier to mix and match than one long variant string. All colors resolve through --loomi-* custom properties, so the whole button can be re-skinned from your page with no rebuild.

Installation

npm install @loomidev/button lit

import "@loomidev/button"; // registers <loomi-button>

Install lit alongside the component. @loomidev/theme (the shared design tokens) is installed automatically.

Basic Usage

Subscribe Now Subscribe Now Subscribe Now

<loomi-button>Subscribe Now</loomi-button>

<!-- uppercase the label -->
<loomi-button uppercase>Subscribe Now</loomi-button>

<!-- render as an <a> tag -->
<loomi-button tag="a" href="/pricing">Subscribe Now</loomi-button>

Button Types

type selects the default hue when color is unset — both render as a bold fill. primary uses the primary palette; secondary uses the secondary palette.

Primary Button Primary Outline Secondary Button Secondary Outline

<loomi-button>Primary Button</loomi-button>
<loomi-button outline>Primary Outline</loomi-button>

<loomi-button type="secondary">Secondary Button</loomi-button>
<loomi-button type="secondary" outline>Secondary Outline</loomi-button>

Outline

Set outline on any button to drop the fill and keep a colored border + text.

Error Outline Secondary Outline Border 4 Border 8

<loomi-button outline color="error" radius="full">Error Outline</loomi-button>
<loomi-button type="secondary" outline radius="full">Secondary Outline</loomi-button>

<!-- custom border width (default is 2) -->
<loomi-button outline border-width="4">Border 4</loomi-button>
<loomi-button outline border-width="8">Border 8</loomi-button>

Sizes

Available sizes: tiny, small, regular (default), medium, big.

Tiny Small Regular (default) Medium Big

<loomi-button size="tiny">Tiny</loomi-button>
<loomi-button size="small">Small</loomi-button>
<loomi-button>Regular (default)</loomi-button>
<loomi-button size="medium">Medium</loomi-button>
<loomi-button size="big">Big</loomi-button>

Radii

None Small Medium Full

<loomi-button radius="none">None</loomi-button>
<loomi-button radius="small">Small</loomi-button>
<loomi-button radius="medium">Medium</loomi-button>
<loomi-button radius="full">Full</loomi-button>

These are presets over the --loomi-control-radius / --loomi-pill-radius theme tokens. radius="medium" (the default) follows your theme — set --loomi-control-radius and every default button reshapes with it. none/small/full set an explicit corner that overrides the theme, so a radius="small" button keeps its shape even under a global radius override. See Theming.

Colors

color overrides the palette independently of type. Useful for semantic actions that shouldn’t use the brand colors (e.g. a destructive delete button).

Delete Account Error Outline Confirm Proceed with Caution

<loomi-button color="error">Delete Account</loomi-button>
<loomi-button color="error" outline>Error Outline</loomi-button>
<loomi-button color="success">Confirm</loomi-button>
<loomi-button color="warning" outline>Proceed with Caution</loomi-button>

Available colors: primary secondary info success error warning gray

Leaving color unset derives it from type: primary → the primary palette, secondary → the secondary palette.

Icons

Set icon to a name from the built-in registry. Icons default to the left; add icon-right to move them after the label. icon-right is ignored while a spinner is showing.

Refresh Page Next Chapter Delete

<loomi-button icon="arrow-path">Refresh Page</loomi-button>
<loomi-button icon="arrow-small-right" icon-right>Next Chapter</loomi-button>
<loomi-button icon="trash" color="error" outline>Delete</loomi-button>

Built-in icons (a subset of Heroicons outline): arrow-path, bell-alert, lock-closed, arrow-right, arrow-small-right, chevron-right, check, plus, trash, x-mark, magnifying-glass, paper-airplane.

Need more? Register your own — no slot or icon font required:

import { registerLoomiIcon } from "@loomidev/button";
import { svg } from "lit";

registerLoomiIcon("star", svg`<path stroke-linecap="round" stroke-linejoin="round" d="..." />`);

Spinners

has-spinner includes a spinner (hidden by default). show-spinner makes it visible. To toggle it on click, call the instance methods startSpinner() / stopSpinner().

Saving… Save User

<!-- visible immediately -->
<loomi-button has-spinner show-spinner>Saving…</loomi-button>

<!-- triggered on click -->
<loomi-button id="save" has-spinner>Save User</loomi-button>
<script type="module">
  const btn = document.getElementById("save");
  btn.addEventListener("click", () => {
    btn.startSpinner();
    saveUser().finally(() => btn.stopSpinner());
  });
</script>

Form Submission

By default the button renders as <button type="button"> and won’t submit forms. Add can-submit to render as <button type="submit">.

Submit Form

<loomi-button can-submit>Submit Form</loomi-button>

Disabled

Disabled Disabled Secondary Disabled Outline

<loomi-button disabled>Disabled</loomi-button>
<loomi-button disabled type="secondary">Disabled Secondary</loomi-button>
<loomi-button disabled outline>Disabled Outline</loomi-button>

Render as a link

Open

<loomi-button tag="a" href="https://example.com" icon="paper-airplane">
  Open
</loomi-button>

When tag="a" and disabled is set, the href is removed and the link is taken out of the tab order.

Focus Rings

No Focus Ring

<!-- hide the keyboard focus ring -->
<loomi-button show-focus-ring="false">No Focus Ring</loomi-button>

Theming

Override any palette slot from your page — no build step, no Tailwind:

:root {
  --loomi-primary-600: #16a34a; /* every primary button turns green */
  --loomi-primary-700: #15803d;
}

Shape and density are themeable the same way, so the radius/size attributes stay as per-instance presets while these set the global default:

:root {
  --loomi-control-radius: 0.25rem; /* default (radius="medium") buttons; also inputs, tags… */
  --loomi-pill-radius: 9999px;     /* radius="full" buttons */
  --loomi-density: 0.9;            /* scales every control's height + padding, not its font */
}

Precedence is per-instance attribute → :root token → built-in default: radius="small" or size="big" on a specific button still wins over these global values.

See the root README for the full theming model.

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
type	primary	Structural variant. primary | secondary
color	(derived from type)	Palette override. See available colors above.
size	regular	tiny | small | regular | medium | big
radius	medium	none | small | medium | full
outline	false	Outline only, no fill. (boolean)
border-width	2	Outline border width. 2 | 4 | 8
icon	(blank)	Built-in or registered icon name.
icon-right	false	Position the icon after the label. Ignored while spinning. (boolean)
has-spinner	false	Include a spinner (hidden until shown). (boolean)
show-spinner	false	Show the spinner. Only when has-spinner. (boolean)
disabled	false	Disable the button. (boolean)
tag	button	Element to render. button | a
href	(blank)	Link target when tag="a".
can-submit	false	Render as type="submit". (boolean)
show-focus-ring	true	Show the keyboard focus ring. (boolean)
uppercase	false	Uppercase the label. (boolean)
name	(blank)	Optional name, reflected as an attribute for targeting.

Properties & methods (JS)

Member	Description
All attributes above	Available as camelCase properties (e.g. el.iconRight, el.hasSpinner).
startSpinner()	Show the spinner (no-op unless has-spinner is set).
stopSpinner()	Hide the spinner.

Slots

For arbitrary content, use the named slots. (For known icon sets, prefer the icon attribute above.)

Profile ▾

<loomi-button>
  <img slot="prefix" src="/avatar.png" width="16" height="16" alt="" />
  Profile
  <span slot="suffix">▾</span>
</loomi-button>

Slot	Description
(default)	The button label.
prefix	Content rendered before the icon/label.
suffix	Content rendered after the label.

Events

The native click event is composed and crosses the shadow boundary, so you listen for it exactly as you would on a normal button:

Click Me

<loomi-button onclick="alert('you clicked me')">Click Me</loomi-button>

Clicks are suppressed while the button is disabled.

CSS Parts

Part	Description
button	The underlying <button> / <a> element.

Full Example

Subscribe

<loomi-button
  type="secondary"
  size="big"
  name="btn-subscribe"
  has-spinner
  tag="a"
  href="/subscribe"
  outline
  border-width="2"
  show-focus-ring="false"
  radius="medium"
  icon="lock-closed"
>
  Subscribe
</loomi-button>

Framework integration

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

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

<loomi-button color="primary" icon="check">Save changes</loomi-button>

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

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

resources/js/app.js

import "@loomidev/button";

<loomi-button color="primary" icon="check">Save changes</loomi-button>

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

export function LoomiExample() {
  return (
    <loomi-button color="primary" icon="check">Save changes</loomi-button>
  );
}

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

<template>
  <loomi-button color="primary" icon="check">Save changes</loomi-button>
</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/button";

@Component({
  selector: "app-root",
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <loomi-button color="primary" icon="check">Save changes</loomi-button>
  `,
})
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/button";
</script>

<loomi-button color="primary" icon="check">Save changes</loomi-button>

---
import "@loomidev/button";
---

<loomi-button color="primary" icon="check">Save changes</loomi-button>

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/icons
• @loomidev/theme