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 Continue Subscribe Now Subscribe Now

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

<!-- fill the container's width (label stays centered) -->
<loomi-button full-width>Continue</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 picks the structure: primary is a bold fill, secondary is an outline (surface fill, 1px border). With color unset, primary uses the primary palette and secondary uses a neutral gray border with dark text. Setting color on a secondary button colors its border and text, exactly like outline color="…" - it stays an outline.

Primary Button Primary Outline Secondary Button Error Secondary

<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" color="error">Error Secondary</loomi-button>

Outline

outline applies to primary (and colored) buttons only. A secondary button is already an outline, so type="secondary" needs no outline attribute - adding one changes nothing, and type="secondary" color="error" renders the same as outline color="error".

Secondary and outline buttons use a surface fill (white in light mode), a thin 1px border, and 6px default corners. Secondary uses a neutral gray border and dark text; colored outlines retain their palette border and text. Theme surface colors adapt in dark mode. Explicit radius presets and --loomi-control-radius overrides still apply.

Error Outline Secondary Border 2

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

<!-- custom border width (default is 1) -->
<loomi-button outline border-width="2">Border 2</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 → a primary fill, secondary → the neutral secondary outline. color never changes a secondary button’s structure, only its hue.

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="..." />`);

Circle

Set circle to render a square, full-radius icon button - for icon-only buttons. Drop the label content and give it an aria-label for the accessible name.

<loomi-button circle icon="trash" color="error" aria-label="Delete"></loomi-button>
<loomi-button circle icon="check" size="small" aria-label="Confirm"></loomi-button>

circle overrides radius and hides any label text, so it’s only meant for icon buttons.

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 (fill) | secondary (outline; color tints border and text)
color	(derived from type)	Palette override. See available colors above.
size	regular	tiny | small | regular | medium | big. See Sizing.
radius	medium	none | small | medium | full
outline	false	Surface fill with colored border and text. Primary only; no effect on secondary. (boolean)
circle	false	Square, full-radius icon button; overrides radius. (boolean)
border-width	1	Secondary/outline border width. 1 | 2
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)
full-width	false	Stretch to fill the container’s width, label centered. (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"
  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