Loaders

When something takes a moment (a workspace being prepared, a model thinking, a build, an upload), show it at work. Each loader is a small scene in perspective, drawn live in your text color with one mark in your accent and a few touches of your theme's colors, on the motion tokens' tempo. It's a status that announces its label politely, and under reduced motion it holds one still frame that still reads as busy.

The loaders gallery shows every one of them live: filter them by category, set the size, the length of a loop, the colors and the labels, then copy the code or the install command.

#The set

#Every loader

A loader's id is its entry, @youj/loaders/<id>, and its component is Loader and the id in PascalCase (tittle is LoaderTittle). The ids, by category:

#Installation

#From the package

Every loader ships in @youj/loaders, at its own entry, as Loader and its name:

import { LoaderTittle } from '@youj/loaders/tittle'

#One loader, as source

To own and edit one loader, copy it in with the Youj CLI in an app set up from source (npx @youj/cli init --mode registry). Every loader is its own item, loader-<id>. It brings the kit the loaders are drawn with (loader-kit: the status, the shared ticker and the engine that draws in depth) and nothing else. In an app on the packages, the same command installs @youj/loaders instead and names the entry to import:

It lands in components/youj/loaders/<category>/<id>.tsx, and you import it from there through your @/ alias:

import { LoaderTittle } from '@/components/youj/loaders/depth/tittle'

Each loader's id, import and install command are on its card in the gallery.

#Usage

import { LoaderSustain } from '@youj/loaders/sustain'

export function Transcript({ busy }: { busy: boolean }) {
  if (busy) return <LoaderSustain size="lg" label="Transcribing" showLabel />
  // …
}

#Size

size is the drawing's height: sm (24px, beside text), default (40px, in a control or a card), lg (64px, on a panel) or any number of pixels. The wordmark loaders and most of the signals are wider than they are tall. Each draws for its size: fewer, bolder marks when it's small, finer detail when it's large.

#Color

A loader's structure is drawn in its ink, the text color (currentColor) by default, so it takes the color of whatever it sits in; color sets it to any CSS color, token references included. Its accent is on the one mark that matters (lit accent faces included) and in a shown label's light and caret: the theme's accent by default, and accentColor sets it the same way.

That is all a loader uses unless you ask for more. Pass colors="theme" and a few parts take colors derived from your accent: what moves or works (a trail, a path being traced) in one, a second layer in another, and a finished state (a check, an arrival) in your success color. The color is quiet: thin marks and small particles, never more than about a third of the drawing, and it moves with the loop, a part warming toward its color on the beat, new marks arriving in color and settling to the ink, a hue travelling once through a structure. The colors are muted and follow your theme's accent, in light and dark, so the accent stays the brightest thing in the drawing.

<LoaderIsobar color="var(--color-fg-muted)" />
<LoaderTittle color="var(--color-fg-muted)" accentColor="var(--color-success)" />

colors is off by default: a loader draws in its ink and its accent alone. colors="theme" turns the colored parts on in the theme's colors. A list sets their colors instead, in order, with any CSS color or token reference; an empty entry, or one you leave out, keeps the theme color. A loader without colored parts ignores it. A loader's parts are named in the gallery, whose Color control switches between Mono (the default) and Theme and, with Theme on, picks each part's color.

<LoaderPrompt colors="theme" />
<LoaderGantry colors={['var(--color-fg-muted)', 'var(--color-success)']} />
<LoaderGantry colors={['', 'var(--color-success)']} />

Solid planes and lit faces hide what's behind them by painting on a paper: --yj-anim-paper, the surface by default. On another background, set it to that background, so the faces sit on what's really there:

<div className="bg-canvas [--yj-anim-paper:var(--color-canvas)]">
  <LoaderCarton size="lg" />
</div>

#Pace

A loop lasts a few beats of the deliberate duration, so the theme's personality and the provider's time scale reach it: in a precise theme a beat is 560ms, and a loop takes a few seconds. speed multiplies on top (2 is twice as fast). A change of speed carries on from the frame it's on, and paused holds the frame.

#Announcing the wait

The status is named by label, "Loading" by default (from the labels, so it's translated with the rest). When something around it already says what's happening (a button that reads "Saving…"), pass label={null} and the loader is only a picture.

#Showing the label

showLabel shows the label with the drawing: centered under it by default, in the theme's label voice, with the space between them (and on a large drawing, the type) growing with size. labelPosition puts it over the drawing (top), or beside it, before (start) or after (end) it in the reading direction, so it changes sides in a right-to-left language. Beside the drawing it takes the text style of the line it sits in. Over or under it, one loader's label can take its own type through the theme's label properties and --yj-label-size: className="[--yj-label-case:uppercase] [--yj-label-font:var(--font-mono)] [--yj-label-size:15px]".

<LoaderBuild size="lg" label="Building" showLabel />
<LoaderTittle size="sm" label="Syncing" showLabel labelPosition="end" />

A shown label moves in time with the drawing, on its clock: it holds when the drawing is paused or off screen, and keeps its pace through speed and the time scale. labelEffect picks how:

<LoaderPrompt size="lg" label="Thinking" showLabel labelEffect="type" />

The drawn label is only a picture of the words: assistive technology hears the plain label once, never letters arriving. It's static in the server's HTML, and starts moving at a moment of the loop that looks just like it, so nothing jumps when the script arrives. In a right-to-left language the effects run from the right. Letters move one by one (wave, and scramble's noise) only in scripts whose letters stand on their own; a joined script such as Arabic keeps its letters whole, wave passing a light through the word and scramble resolving it as a plain reveal.

#Rotating labels

A wait that takes a while can say more than one thing. Give label a list, and a shown label turns through it: each one shows for labelEvery loops (one by default), and the next takes over at the loop's seam, the effect carrying the change: the light dips, the letters lift away and rise in, the caret clears one and types the next, the noise resolves into it, or the line rolls up. Then it starts again from the first.

<LoaderBuild
  size="lg"
  label={['Building', 'Bundling', 'Optimizing images', 'Deploying']}
  showLabel
  labelEffect="slide"
/>

<LoaderTittle
  size="lg"
  label={['Loading', 'Generating results', 'Almost there']}
  labelEvery={2}
  showLabel
  labelEffect="wave"
/>

The labels sit in one place as wide as the longest, so nothing around them moves as they change. The status doesn't read each one out: it says the first, then a later one only as it shows, in order, once each and at least ten seconds after the last, and then it stays quiet, however long the wait. When the state really changes (an upload finishes and processing starts), pass a new label: that's said at once. Without showLabel, the labels still take turns for assistive technology the same way. Under reduced motion the first label shows, still, and stays.

#Performance

Each loader draws on one small canvas, on a ticker every loader on the page shares, and only while it's on screen in a visible tab: offscreen, hidden or paused, it costs nothing. Its colors are read once, and again when the theme changes. The server sends its still frame as SVG, so it's never blank before the script runs.

#Reference