Loader

When to use

Reach for dots or spinner for a small, in-place "this is working" indicator, such as inside a button while it submits, next to a field while it validates, or in a table cell while a value loads. Reach for bar for a wider, section or page-level indicator, such as above a page while it loads or atop a panel while its content refreshes, indeterminate by default, or determinate once there's actual progress to report, such as an upload or a multi-step process. None of the three are built for a whole page or route's first load. For that, show skeleton placeholders instead, so the layout doesn't jump once the real content arrives. For a scalar measurement within a known range that's never an unknown duration, such as disk usage, a score, or a battery level, reach for progress bar instead, since it has no indeterminate state. See Alternatives below for a side by side comparison.

Install & usage

Pick a framework in the toolbar above and these snippets adapt.

npm install @eunomia/elements

import "@eunomia/elements/loader.js";

<eun-loader></eun-loader> <eun-loader variant="spinner"></eun-loader>

npm install @eunomia/elements

<script type="module">
  import "@eunomia/elements/loader.js";
</script>

<eun-loader></eun-loader>

npm install @eunomia/elements

import "@eunomia/elements/loader.js";

function Spinner() {
  return <eun-loader variant="spinner" aria-label="Loading results" />;
}

npm install @eunomia/elements

"use client";
import "@eunomia/elements/loader.js";

export function Spinner() {
  return <eun-loader variant="spinner" />;
}

npm install @eunomia/elements

<script setup>
  import "@eunomia/elements/loader.js";
</script>

<template>
  <eun-loader variant="spinner" />
</template>

npm install @eunomia/elements

import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
import "@eunomia/elements/loader.js";

@Component({
  selector: "app-spinner",
  template: `<eun-loader variant="spinner"></eun-loader>`,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class SpinnerComponent {}

Alternatives

Guidance

Live testing

Properties

Dots (default)

Used internally by eun-button's own loading state: compact enough to sit inside a button, badge, or table cell without changing its surrounding layout.

<eun-loader></eun-loader>

Spinner

A rotating ring, meant for a standalone or field-level indicator, e.g. the loading state on eun-search and eun-select.

<eun-loader variant="spinner"></eun-loader>

Inherits color and size

Both variants use currentColor and em-relative sizing by default, so they automatically match whatever text color/font-size surrounds them.

<div style="color: #148cd2; font-size: 24px;">
  <eun-loader></eun-loader>
  <eun-loader variant="spinner"></eun-loader>
</div>

Custom size

Set size to override the inherited font-size directly, without touching the surrounding text.

<eun-loader size="32"></eun-loader>
<eun-loader variant="spinner" size="32"></eun-loader>

Bar

A full-width variant for a section- or page-level indicator, indeterminate by default or switched to a determinate fill, optionally pinned in place while its surroundings scroll.

Indeterminate

Left with no value, bar sweeps continuously: a full-width "work is happening, duration unknown" indicator.

<eun-loader variant="bar" label="Loading results…"></eun-loader>

Determinate

Set value (0–100) to switch it to a fixed-width fill instead: an upload, a multi-step process, anything with real, measurable progress.

<eun-loader variant="bar" value="25" label="Uploading…"></eun-loader>

Sticky

Set sticky to pin the bar to an edge of its nearest scrolling ancestor via position: sticky, for a page-level bar that stays visible while the page scrolls underneath it. stickyPosition picks which edge : top (the default) or bottom.

<div class="scroll-container">
  <eun-loader variant="bar" sticky label="Loading feed…"></eun-loader>
  <!-- scrolling content -->
</div>

Set sticky-position="bottom" to pin it to the bottom edge instead, e.g. above a fixed footer or toolbar.

<div class="scroll-container">
  <!-- scrolling content -->
  <eun-loader
    variant="bar"
    sticky
    sticky-position="bottom"
    label="Loading feed…"
  ></eun-loader>
</div>

Custom styling

Override the --loader-bar-* CSS variables: full list in the API tab.

<eun-loader
  variant="bar"
  value="55"
  label="Custom styled bar"
  class="custom-bar"
></eun-loader>

.custom-bar {
  --loader-bar-track-height: 14px;
  --loader-bar-track-color: #ede9fe;
  --loader-bar-fill-color: #7c3aed;
  --loader-bar-border-radius: 4px;
}

Aria attributes

dots/spinner render role="status" with aria-label (from the label property, default "Loading…"): a screen reader announces it as a live, polite status update rather than silently rendering a purely visual animation with no accessible meaning. role="status" implies an aria-live="polite" region on its own, per the ARIA specification, so no extra live-region wiring is needed around it.

bar renders role="progressbar" instead, with aria-label, aria-valuemin="0", and aria-valuemax="100" always present. In indeterminate mode (no value set), aria-valuenow is intentionally omitted: per the ARIA specification, a progressbar with no aria-valuenow is itself the signal that progress is indeterminate, the same way it's communicated visually by the sweeping fill. Once value is set, aria-valuenow is added (clamped to 0–100), switching both the visual fill and the accessible state to determinate together.

Dynamic updates aren't announced on their own

role="progressbar" doesn't imply a live region the way role="status" does: a screen reader won't automatically re-announce bar's value as it changes. If the progress needs to be heard as it updates (a multi-step upload, for instance), pair it with your own visually-hidden aria-live="polite" region that you update alongside value, rather than relying on the bar itself.

<eun-loader variant="bar" value="40" label="Uploading…"></eun-loader>
<span class="sr-only" aria-live="polite">40% uploaded</span>

Motion

Every variant keeps animating under prefers-reduced-motion: reduce, just significantly slower, rather than freezing solid: a loading indicator communicates a real, ongoing state change, and a fully static spinner, dots row, or indeterminate bar would read as broken/stuck rather than "still loading", worse for a reduced-motion user than no indicator at all. A determinate bar's width transition, on the other hand, isn't itself the "is it working" signal: the fill's actual position already communicates that on every render, so it isn't slowed under reduced motion.

Reference links

WAI-ARIA: status role
WAI-ARIA: progressbar role
WCAG 2.1: Animation from Interactions