Loading

Every loader is its own component and they all take the same parameters, so picking one is purely a question of which animation suits the surface. Nothing here needs to be configured: a bare tag renders a 64px drawing in the theme's primary color that loops until it is removed from the page. What separates them is weight - a ring or a spinner is quiet enough to sit inside a control, while the heart, the hourglass or the rolling square are large gestures better suited to an empty page.

Label is what turns a spinning shape into a status message, and it is also what a screen reader announces in place of the default text described under Accessibility. Prefer something specific and present-tense - "Uploading photos..." says far more than "Loading" - and keep it to a few words: the label scales with the Size of the loader, so a sentence quickly grows wider than the drawing it sits under.

LabelPosition puts the label on any of the four sides of the drawing. Top is the default. Start and End follow the direction of the writing and swap sides in a right-to-left layout, while Top and Bottom stay where they are.

LabelTemplate replaces the label with markup of your own - a second line, a link, an elapsed-time counter - and it takes the place of Label when both are given. It sits in the same slot, so LabelPosition still decides which side of the drawing it lands on, and it counts as a visible label, so the loader stops rendering its hidden fallback text and announces the template instead.

Speed is a multiplier over the animation's normal pace: 2 runs it twice as fast, 0.5 half as fast. Every duration and every delay inside the loader is scaled together, so the phase offsets that stagger its parts against each other survive rather than bunching up. The multiplier composes with the reduced-motion preference instead of overriding it - a loader in a reduced-motion environment still runs at the calmer pace the theme picks, only scaled by this value - which is why a fast loader is safe to reach for. Zero and negative values are ignored.

Paused holds the animation at the frame it had reached instead of removing it. The drawing keeps its shape and its place in the layout, so pausing and resuming never makes the surface around it jump, and the live region stays exactly as it was - it is the movement alone that stops. A paused loader still says that work is under way, so reach for it only where that remains true and the movement is what has to stop: a wait that has stalled behind a retry, or a page whose animations are held while it is captured. Once the work is over, remove the component rather than pausing it.

Work that finishes inside a few hundred milliseconds reads as instant, and a loader that flashes up and vanishes again inside that window is more distracting than no loader at all. Delay holds the component back for that many milliseconds before it shows anything: if the work finishes first, the loader is removed before the delay elapses and nothing was ever shown; if it does not, the loader appears as usual. Changing the number opens the window again from the new length, and setting it back to zero lets the loader through at once, so one kept in the document across several waits can be held back for each of them without being re-created.

Thickness sets the width, in pixels, of the stroke the drawing is made of. Only the loaders drawn with a stroke read it - BitRingLoading, BitDualRingLoading, BitRippleLoading, BitXboxLoading and BitSpinnerLoading - and the rest, whose shapes are filled rather than stroked, are left as they are. Each of them draws the stroke inside its own outline, so a thicker one never grows the footprint of the component past the size it was given.

It is a literal number of pixels rather than a ratio, so it does not scale with Size: a hairline stays a hairline whatever the loader is sized at, which is what lets a 16px inline loader and an 88px one on an empty page read as the same weight of line. Zero and negative values are ignored, and leaving it unset keeps the thickness each drawing was authored with.

A loader is a block of its own by default, sized in pixels and centred on its own line. Inline lays it out as an inline box aligned to the middle of the current line instead, so it can sit inside a sentence, a button, a table cell or a heading without pushing anything onto a new line. Pair it with a small CustomSize and with CustomColor="currentColor", which takes the color of the text around it.

Fetching the latest results please wait.

A spinning shape says nothing on its own, so the root element is a live region: it carries role="status" and aria-live="polite", and its text is announced when the loader appears. That text is the Label when there is one; without a label the component renders a visually hidden "Loading" instead, which AriaLabel replaces with wording of your own. The drawing itself is marked aria-hidden, so none of its geometry is walked by a screen reader.

Role and AriaLive change that contract where the surroundings call for it. Role="progressbar" suits a wait that is measured and reported through the aria-value attributes - but everything inside a progressbar is presentational, so a visible label is no longer announced from within it. Role="none" silences a purely decorative loader whose surroundings already report the wait, which is the right choice when several loaders appear at once. AriaLive="assertive" interrupts the screen reader rather than waiting for it, and is only appropriate where the wait itself is what the user has to hear about right now.

Color paints the whole drawing in one of the theme's roles, so a loader re-skins with the rest of the library when the theme or the color scheme changes. CustomColor takes any valid CSS color instead - a keyword, a hex value, rgb(), hsl(), and currentColor to inherit the color of the surrounding text - and only applies while Color is left unset, since a theme role always wins over a literal color.

Theme colors:

Custom colors:

Size offers the three sizes shared across the library - Small (40px), Medium (64px, the default) and Large (88px) - and CustomSize takes any number of pixels for the cases those three do not cover, such as the 16px loader that fits inside a line of text. Everything scales together: the drawing, the strokes it is built from and the label under it. CustomSize only applies while Size is left unset.

Style and Class land on the root of the component - the box that holds the drawing and the label - while Styles and Classes reach every part of it on its own: the root, the container of the animation, each of its child elements, the label, and the visually hidden text a labelless loader announces. The loader also reads a handful of CSS variables off its root, for what no parameter covers: --bit-ldn-color for the color of the drawing, --bit-ldn-size for its size in pixels, --bit-ldn-font-size for the label, --bit-ldn-stroke for the width of the stroke, which is what Thickness writes over, and --bit-ldn-mot-factor for the factor every duration and delay inside it is multiplied by, which is what Speed writes over.

Component's Style & Class:

CSS variables:

Styles & Classes:

Use BitLoading in right-to-left (RTL). Most of the animations turn about their own centre and look the same either way, so what the direction usually changes is the label: Start and End follow the direction of the writing and move to the other side of the drawing with it, while Top and Bottom stay where they are.

The two loaders whose motion actually travels across the box - the ellipsis, whose dots march along, and the rolling square - are mirrored instead, so that they run toward the end of the line the way an indeterminate progress bar does rather than always to the right.