# Spinner

An indicator that can be used to show a loading state.

Source: https://webjs.dev/ui/docs/components/spinner

```ts
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>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add spinner
```

### Copy and paste the following code into your project.

````ts title="components/ui/spinner.ts"
/**
 * 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

```ts
import { spinner } from '#components/ui/spinner.ts';
```

```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.

```ts
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>
  `;
}
```

```ts title="components/ui/spinner.ts"
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.

```ts
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>
  `;
}
```

## 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.

```ts
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>
  `;
}
```

## 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.

```ts
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>
  `;
}
```

## Input Group

```ts
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>
  `;
}
```

## Empty

```ts
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>
  `;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

```ts
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>
  `;
}
```
