Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Sizes

Use sm inline with text or inside a control, and md alone in a small area; give each spinner a label.

sm and md
Give it a label when the page has more than one. “Loading” twice tells a screen reader nothing about which.
Show code
<app-spinner size="CompactSize.Sm" label="Checking availability" />
<app-spinner />
Any pixel size
Pass a number to set the exact diameter. The spinner scales its own border to match, so it stays crisp at any size.
Show code
<app-spinner size-px="16" />
<app-spinner size-px="28" />
<app-spinner size-px="48" />

Busy buttons

A button's loading prop draws its own spinner and disables the button, so never put a spinner inside it.

Inside a button
Use the loading attribute rather than putting a spinner in the label. app-button's loading attribute renders its own spinner and disables the button, so don't compose the two by hand.
Show code
<app-button loading="true">Saving…</app-button>

Spinner or skeleton

Prefer a skeleton for content with a known shape, since it shows what is coming; a spinner suits a small wait.

The same wait, two ways
Left: a spinner in the middle of an empty area. The reader learns nothing and the layout will shift. Right: rows in the shape of the table that is loading.
Show code
@* Prefer this for above-the-fold content *@
<table class="table table-ledger">
  <tbody>
    <tr>
      <td><app-skeleton width="70%" height="12px" /></td>
      <td><app-skeleton width="50%" height="12px" /></td>
    </tr>
  </tbody>
</table>

@* A spinner is right for a small, shapeless wait *@
<app-spinner size="CompactSize.Sm" label="Checking availability" />

Every option

Every value of every prop, one cell each.

size: presets and exact pixel diameters

(default) size="md"
size="sm"
size="16"
size="24"
size="32"
size="48"
size="64"

label

(default) label="Loading"
label="Checking availability"

class passthrough

class="text-primary"
class="text-danger" size="sm"

Guidance

What to do, and what to avoid.

Use it when

  • A short, shapeless wait, such as a validity check or an inline recalculation.
  • The busy area is too small for a skeleton to read as anything.
  • You need a busy indicator next to a status line or in a table cell.

Reach for something else when

  • Content with a known shape is loading. → AppSkeleton / AppSkeletonRows
  • A button is submitting. → AppButton's loading prop
  • The whole app is booting. → AppSplash
  • The wait finished and there is nothing to show. → AppEmptyState

Name what is loading

Do

A label that says what is happening, sized to sit inline with the thing it belongs to.

Avoid

A lone spinner filling a content area: no indication of what is loading, no idea how long, and the layout will jump when the real content arrives.

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

sm md
(none) 16 24 32 48 64
React, generated from the controls
<AppSpinner />
Razor, the same props
<app-spinner />

3 props. The 2 most used come first.

Used on most screens 2 props

PropTypeDefaultDescription
sizedefault md Sm | Md md A preset (sm or md); the border scales with it.
labeldefault Loading string Loading Accessible name.

Less common 1 props

PropTypeDefaultDescription
size-pxdefault - number - The size in pixels, instead of a preset.

Screen reader

1 notes
  • The spinner is a span with role status, named by label, which is Loading unless you set it.

Do and avoid

1 pairs

Name what is loading

Do

A label that says what is happening, sized to sit inline with the thing it belongs to.

Avoid

A lone spinner filling a content area: no indication of what is loading, no idea how long, and the layout will jump when the real content arrives.