Loader
A loader tells users that content, assets or UI elements are on their way, so a wait doesn’t read as a broken page.
Loading search results...
Usable — may still change
The loader gives feedback while content, assets or UI elements load. It combines a circular progress indicator with a label that says what is happening, and can offer an action such as retrying, cancelling or resetting. Once loading completes, it is removed and replaced by the loaded content.
Anatomy
Section titled “Anatomy”Loading
- Loader
- Progress indicator
- Icon
- Label
- Action button
When to use it
Section titled “When to use it”Use a loader when there is a wait for content, assets or UI elements to load. Once loading completes, remove it and show the loaded content in its place.
Properties
Section titled “Properties”Type
Determinate shows measured progress from 0% to 100%. Indeterminate runs while the duration or completion percentage is unknown.
Icon
An optional decorative icon inside the progress indicator. It reinforces the loading state but carries no information.
Label
Says what is loading. Show it whenever possible, as it gives more meaningful feedback than the graphic alone. Hiding it is an edge case.
Action button
An optional main button below the loader, for retrying, cancelling or resetting when the user has to step in. It keeps the button’s own behaviour, states and content guidance.
Lexus gradient
Section titled “Lexus gradient”On Lexus the progress indicator is drawn in the copper gradient. The gradient is a visual enhancement: the loading state has to remain understandable without it.
Content guidelines
Section titled “Content guidelines”Describe what is loading whenever you can. Generic text is only for when there is no more context to give.
- Preferred: “Loading your experience…”, “Loading search results…”, “Retrieving vehicle details…”
- Acceptable: “Loading…”
Keep labels short and easy to scan, ideally on a single line, and avoid lengthy explanations.
When you show an action button, use the main button and follow its content guidance.
A loader is a tng-loader holding a tng-loader-status, which groups the tng-loader-progress ring and the tng-loader-label. Its width defaults to 191px; set --tng-loader-inline-size to change it. Mount it for the wait and remove it afterwards, or toggle hidden.
<div class="tng-loader"> <div class="tng-loader-status" role="status"> <div class="tng-loader-progress"></div> <p class="tng-loader-label">Loading search results...</p> </div></div>Loading search results...
Elements
Section titled “Elements”Put a decorative tng-icon is-md inside the ring.
<div class="tng-loader"> <div class="tng-loader-status" role="status"> <div class="tng-loader-progress"> <i class="tng-icon is-md icon-ai-sparkle" aria-hidden="true" ></i> </div> <p class="tng-loader-label">Loading search results...</p> </div></div>Loading search results...
Hidden label
Section titled “Hidden label”Add sr-only to keep the label for screen readers when it has to stay off screen.
<div class="tng-loader"> <div class="tng-loader-status" role="status"> <div class="tng-loader-progress"></div> <p class="tng-loader-label sr-only">Loading search results...</p> </div></div>Loading search results...
Action button
Section titled “Action button”A tng-button as a direct child fills the loader’s width.
<div class="tng-loader"> <div class="tng-loader-status" role="status"> <div class="tng-loader-progress"></div> <p class="tng-loader-label">Loading search results...</p> </div> <button class="tng-button is-primary is-lg" type="button"> <span>Reset progress</span> <i class="tng-icon icon-arrow-right" aria-hidden="true"></i> </button></div>Loading search results...
Indeterminate
Section titled “Indeterminate”A ring without aria-valuenow keeps sweeping from 0° to 360°. Under prefers-reduced-motion it holds a static three-quarter arc.
Determinate
Section titled “Determinate”A ring with aria-valuenow stops sweeping and draws --tng-loader-progress, a number from 0 to 1. Update both as loading advances.
<div class="tng-loader"> <div class="tng-loader-status" role="status"> <div class="tng-loader-progress" role="progressbar" aria-labelledby="loader-determinate-label" aria-valuemin="0" aria-valuemax="100" aria-valuenow="40" style="--tng-loader-progress: 0.4" ></div> <p class="tng-loader-label" id="loader-determinate-label"> Loading search results... </p> </div></div>Loading search results...
A loader is a status message: users of assistive technologies hear that something is loading without losing their place. When progress can be measured, it also follows the progressbar role. There is no dedicated WAI-ARIA APG pattern. Handled this way, it meets WCAG 2.1 AA.
For designers
Section titled “For designers”- Show the label whenever possible: it is the primary source of context, and the icon and gradient must never be needed to understand the loading state. Source: WCAG 1.4.1 Use of Color.
- Keep the label readable against its surface. Source: WCAG 1.4.3 Contrast (Minimum).
- When the label is hidden, the ring alone carries the loading state, so it needs enough contrast against its surface. Source: WCAG 1.4.11 Non-text Contrast.
- Let the label wrap rather than truncate, so it survives text resizing and zoom. Source: WCAG 1.4.4 Resize Text.
For developers
Section titled “For developers”Say that loading started, keep saying it consistently while it runs, and say when it finished. The label comes before the action button in the DOM, so it is read first. Source: WCAG 1.3.2 Meaningful Sequence.
The action button is a native <button> and keeps its keyboard behaviour. Source: WCAG 2.1.1 Keyboard.
The sweep stops under prefers-reduced-motion, and the static arc still reads as loading.
Labelling elements
Section titled “Labelling elements”Status
role="status" on tng-loader-status announces the label politely. A live region only announces changes made after it is in the DOM, so render it with an empty label and set the text afterwards. Source: WCAG 4.1.3 Status Messages.
Indeterminate ring
No role and no name: the label carries the meaning, and the ring is decorative. A label hidden with sr-only stays announced.
Determinate ring
role="progressbar", named by the label through aria-labelledby, with aria-valuemin, aria-valuemax and aria-valuenow. Value changes aren’t announced by themselves, so update the label at meaningful milestones. Source: WCAG 4.1.2 Name, Role, Value.
Icon
aria-hidden="true". It is decorative and must not be announced.
Action button
Named by its visible text, which should say what it does: “Retry”, “Cancel loading”.
Loading region
aria-busy="true" on the region being filled while the loader shows. Removing the loader is silent, so when it goes, drop aria-busy and announce completion from a role="status" region that outlives it, for example “Search results loaded”.
Source: WCAG 4.1.2 Name, Role, Value.