import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
itemClass, itemMediaClass, itemContentClass, itemTitleClass,
} from '#components/ui/item.ts';
import { spinner } from '#components/ui/spinner.ts';
export default function SpinnerDemo() {
return html`
<div class="flex w-full max-w-xs flex-col gap-4 [--radius:1rem]">
<div data-slot="item" data-variant="muted" data-size="default" class=${itemClass({ variant: 'muted' })}>
<div data-slot="item-media" data-variant="default" class=${itemMediaClass()}>
${spinner()}
</div>
<div data-slot="item-content" class=${itemContentClass()}>
<div data-slot="item-title" class=${cn(itemTitleClass(), 'line-clamp-1')}>Processing payment...</div>
</div>
<div data-slot="item-content" class=${cn(itemContentClass(), 'flex-none justify-end')}>
<span class="text-sm tabular-nums">$100.00</span>
</div>
</div>
</div>
`;
}
View Code
Installation
Copy and paste the following code into your project.
/**
* Spinner: an animated busy indicator. Tier-1 helpers, `spinnerClass()` for
* the classes and `spinner()` for the whole inline SVG (the Lucide
* loader-circle path, so no icon package is needed). It inherits the text
* colour through `currentColor`, so it matches whatever it sits in.
*
* shadcn parity:
* Spinner → spinner({ class, label }) (the inline SVG)
* → spinnerClass() (the classes, for your own SVG)
*
* Size it with a size utility: `spinner({ class: 'size-6' })` replaces the
* default `size-4`.
*
* Design tokens used: none (it draws in `currentColor`).
*
* A11y (required for accessible output):
* `spinner()` renders `role="status"` + `aria-label="Loading"`, so a
* standalone spinner is announced. Pass `label` for a more specific name
* (`spinner({ label: 'Loading invoices' })`).
* Inside a BUTTON while a save is running, mark the button itself busy:
* `disabled` (so a second click cannot submit twice) plus `aria-busy="true"`,
* and keep a visible text label ("Saving"). The button's text already says
* what is happening, so pass `decorative: true`, which renders the SVG with
* `aria-hidden="true"` and no role, rather than nesting a second live status
* inside the button's name. Re-enable the button and drop `aria-busy` when
* the save settles, and report the outcome somewhere that is announced (a
* toast, or the form's error text).
* A spinner that replaces a whole region is better as a skeleton when the
* final layout is known, with `aria-busy="true"` on the region.
*
* @example
* ```html
* <div class="flex items-center gap-2 text-sm text-muted-foreground">
* ${spinner()} Loading invoices
* </div>
*
* <button class=${buttonClass()} type="submit" disabled aria-busy="true">
* ${spinner({ decorative: true })} Saving
* </button>
* ```
*/
import { html, nothing } from '@webjsdev/core';
import { cn } from '../lib/utils.ts';
/** Spinner classes: `size-4` plus `animate-spin`. Apply to your own `<svg>`. */
export const spinnerClass = (): string => 'size-4 animate-spin';
/**
* The spinner as an inline SVG template. `class` is merged over
* `spinnerClass()` (a later size utility wins), `label` names it (default
* "Loading"), and `decorative` hides it from assistive tech for use beside
* visible text such as a busy button's label.
*/
export function spinner(opts: { class?: string; label?: string; decorative?: boolean; icon?: 'inline-start' | 'inline-end' } = {}) {
const cls = cn(spinnerClass(), opts.class);
// shadcn's `data-icon`, which a button or badge reads to tighten its padding
// on the spinner's side. Left out, the attribute is omitted.
const icon = opts.icon ?? nothing;
// Branched rather than a nullish `role=${...}` hole: the server renderer
// stringifies a null attribute value, so a single template would serve
// `role=""` on the decorative form.
if (opts.decorative) {
return html`<svg data-slot="spinner" data-icon=${icon} aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class=${cls}><path d="M21 12a9 9 0 1 1-6.219-8.56" /></svg>`;
}
return html`<svg data-slot="spinner" data-icon=${icon} role="status" aria-label=${opts.label ?? 'Loading'} xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class=${cls}><path d="M21 12a9 9 0 1 1-6.219-8.56" /></svg>`;
}
Update the import paths to match your project setup.
Usage
import { spinner } from '#components/ui/spinner.ts';
${spinner()}
Customization
You can replace the default spinner icon with any other icon by editing the spinner() function, or by putting spinnerClass() on an SVG of your own.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { spinnerClass } from '#components/ui/spinner.ts';
// The spinner with Lucide's loader icon in place of the default
// loader-circle: the same classes and the same status role, a different path.
function Spinner(opts: { class?: string } = {}) {
return html`<svg data-slot="spinner" role="status" aria-label="Loading" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class=${cn(spinnerClass(), opts.class)}><path d="M12 2v4" /><path d="m16.2 7.8 2.9-2.9" /><path d="M18 12h4" /><path d="m16.2 16.2 2.9 2.9" /><path d="M12 18v4" /><path d="m4.9 19.1 2.9-2.9" /><path d="M2 12h4" /><path d="m4.9 4.9 2.9 2.9" /></svg>`;
}
export default function SpinnerCustom() {
return html`
<div class="flex items-center gap-4">
${Spinner()}
</div>
`;
}
View Code
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
export const spinnerClass = (): string => 'size-4 animate-spin';
export function spinner(opts: { class?: string; label?: string } = {}) {
return html`<svg
data-slot="spinner"
role="status"
aria-label=${opts.label ?? 'Loading'}
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
stroke-linejoin="round"
class=${cn(spinnerClass(), opts.class)}
>
<path d="M12 2v4" /><path d="m16.2 7.8 2.9-2.9" /><path d="M18 12h4" />
<path d="m16.2 16.2 2.9 2.9" /><path d="M12 18v4" /><path d="m4.9 19.1 2.9-2.9" />
<path d="M2 12h4" /><path d="m4.9 4.9 2.9 2.9" />
</svg>`;
}
Size
Pass a size-* utility class through the class option to change the size of the spinner.
import { html } from '@webjsdev/core';
import { spinner } from '#components/ui/spinner.ts';
export default function SpinnerSize() {
return html`
<div class="flex items-center gap-6">
${spinner({ class: 'size-3' })}
${spinner({ class: 'size-4' })}
${spinner({ class: 'size-6' })}
${spinner({ class: 'size-8' })}
</div>
`;
}
View Code
Button
Add a spinner to a button to indicate a loading state. Place spinner({ decorative: true }) before the label for a start position, or after the label for an end position, and mark the button disabled with aria-busy="true" while it waits. The button's text already says what is happening, so the spinner stays hidden from assistive technology.
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { spinner } from '#components/ui/spinner.ts';
export default function SpinnerButton() {
return html`
<div class="flex flex-col items-center gap-4">
<button type="button" data-slot="button" data-variant="default" data-size="sm" disabled aria-busy="true" class=${buttonClass({ size: 'sm' })}>
${spinner({ decorative: true })}
Loading...
</button>
<button type="button" data-slot="button" data-variant="outline" data-size="sm" disabled aria-busy="true" class=${buttonClass({ variant: 'outline', size: 'sm' })}>
${spinner({ decorative: true })}
Please wait
</button>
<button type="button" data-slot="button" data-variant="secondary" data-size="sm" disabled aria-busy="true" class=${buttonClass({ variant: 'secondary', size: 'sm' })}>
${spinner({ decorative: true })}
Processing
</button>
</div>
`;
}
View Code
Badge
Add a spinner to a badge to indicate a loading state. Place spinner({ decorative: true }) before the label for a start position, or after the label for an end position.
import { html } from '@webjsdev/core';
import { badgeClass } from '#components/ui/badge.ts';
import { spinner } from '#components/ui/spinner.ts';
export default function SpinnerBadge() {
return html`
<div class="flex items-center gap-4 [--radius:1.2rem]">
<span data-slot="badge" data-variant="default" class=${badgeClass()}>
${spinner({ decorative: true })}
Syncing
</span>
<span data-slot="badge" data-variant="secondary" class=${badgeClass({ variant: 'secondary' })}>
${spinner({ decorative: true })}
Updating
</span>
<span data-slot="badge" data-variant="outline" class=${badgeClass({ variant: 'outline' })}>
${spinner({ decorative: true })}
Processing
</span>
</div>
`;
}
View Code
Input Group
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
inputGroupClass, inputGroupAddonClass, inputGroupButtonClass,
inputGroupInputClass, inputGroupTextareaClass,
} from '#components/ui/input-group.ts';
import { spinner } from '#components/ui/spinner.ts';
import { ArrowUpIcon } from '#lib/ui/lucide.ts';
export default function SpinnerInputGroup() {
return html`
<div class="flex w-full max-w-md flex-col gap-4">
<div data-slot="input-group" role="group" class=${inputGroupClass()}>
<input data-slot="input-group-control" placeholder="Send a message..." aria-label="Message" disabled class=${inputGroupInputClass()}>
<div data-slot="input-group-addon" data-align="inline-end" class=${inputGroupAddonClass({ align: 'inline-end' })}>
${spinner()}
</div>
</div>
<div data-slot="input-group" role="group" class=${inputGroupClass()}>
<textarea data-slot="input-group-control" placeholder="Send a message..." aria-label="Message" disabled class=${inputGroupTextareaClass()}></textarea>
<div data-slot="input-group-addon" data-align="block-end" class=${inputGroupAddonClass({ align: 'block-end' })}>
${spinner({ decorative: true })} Validating...
<button type="button" data-slot="button" data-variant="default" data-size="xs" class=${cn(inputGroupButtonClass({ variant: 'default' }), 'ml-auto')}>
${ArrowUpIcon()}
<span class="sr-only">Send</span>
</button>
</div>
</div>
</div>
`;
}
View Code
Empty
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
emptyClass, emptyHeaderClass, emptyMediaClass, emptyTitleClass,
emptyDescriptionClass, emptyContentClass,
} from '#components/ui/empty.ts';
import { spinner } from '#components/ui/spinner.ts';
export default function SpinnerEmpty() {
return html`
<div data-slot="empty" class=${cn(emptyClass(), 'w-full')}>
<div data-slot="empty-header" class=${emptyHeaderClass()}>
<div data-slot="empty-icon" data-variant="icon" class=${emptyMediaClass({ variant: 'icon' })}>
${spinner()}
</div>
<div data-slot="empty-title" class=${emptyTitleClass()}>Processing your request</div>
<div data-slot="empty-description" class=${emptyDescriptionClass()}>
Please wait while we process your request. Do not refresh the page.
</div>
</div>
<div data-slot="empty-content" class=${emptyContentClass()}>
<button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${buttonClass({ variant: 'outline', size: 'sm' })}>
Cancel
</button>
</div>
</div>
`;
}
View Code
RTL
To enable RTL support, see the RTL configuration guide.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
itemClass, itemMediaClass, itemContentClass, itemTitleClass,
} from '#components/ui/item.ts';
import { spinner } from '#components/ui/spinner.ts';
const translations = {
en: {
dir: 'ltr',
values: {
title: 'Processing payment...',
amount: '$100.00',
},
},
ar: {
dir: 'rtl',
values: {
title: 'جاري معالجة الدفع...',
amount: '١٠٠.٠٠ دولار',
},
},
he: {
dir: 'rtl',
values: {
title: 'מעבד תשלום...',
amount: '$100.00',
},
},
};
export default function SpinnerRtl() {
const lang = 'ar';
const { dir, values: t } = translations[lang];
return html`
<div class="flex w-full max-w-xs flex-col gap-4 [--radius:1rem]" dir=${dir} lang=${lang}>
<div data-slot="item" data-variant="muted" data-size="default" class=${itemClass({ variant: 'muted' })}>
<div data-slot="item-media" data-variant="default" class=${itemMediaClass()}>
${spinner()}
</div>
<div data-slot="item-content" class=${itemContentClass()}>
<div data-slot="item-title" class=${cn(itemTitleClass(), 'line-clamp-1')}>${t.title}</div>
</div>
<div data-slot="item-content" class=${cn(itemContentClass(), 'flex-none justify-end')}>
<span class="text-sm tabular-nums">${t.amount}</span>
</div>
</div>
</div>
`;
}