bo-loading-ring

bo-loading-ring provides an accessible progress indicator with a 3D ring animation and optional status text.

Basic usage

<bo-loading-ring loader-text="Loading data" />

Loading data

Props

Optional

Name	Type	Description
id	string	Unique identifier for the loader ring container.
dataTestId	string	Deterministic data test id for end-to-end tests.
size	BoSize	The visual size of the ring.
variant	BoLoaderVariant	Predefined color palette for the ring.
customColor	string	Custom CSS color for the ring (hex, rgb(a), oklch, or CSS var).
loaderText	string	Optional text describing the loading state.
textPosition	BoLoaderTextPosition	Placement of the text relative to the ring.
ariaLive	AriaLive	Screen reader politeness for live updates.
ariaLabel	string	Accessible label describing the loading state.
ariaBusy	boolean	Marks the region as busy while the ring is visible.
customContainerCssClass	string	Additional CSS classes appended to the container element.
customRingClass	string	Additional CSS classes appended to the ring element.

Sizes

The ring supports the same sizing scale as the rest of the design system via BoSize.

extra small

small

default

large

extra large

<bo-loading-ring :size="BoSize.extra_small" loader-text="extra small" />
<bo-loading-ring :size="BoSize.small" loader-text="small" />
<bo-loading-ring :size="BoSize.default" loader-text="default" />
<bo-loading-ring :size="BoSize.large" loader-text="large" />
<bo-loading-ring :size="BoSize.extra_large" loader-text="extra large" />

Variants

Use variant to switch between predefined color palettes. For custom brand colors, pass a valid CSS color string to customColor.

primary

secondary

success

warning

danger

dark

light

<bo-loading-ring :variant="BoLoaderVariant.primary" loader-text="primary" />
<bo-loading-ring :variant="BoLoaderVariant.secondary" loader-text="secondary" />
<bo-loading-ring :variant="BoLoaderVariant.success" loader-text="success" />
<bo-loading-ring :variant="BoLoaderVariant.warning" loader-text="warning" />
<bo-loading-ring :variant="BoLoaderVariant.danger" loader-text="danger" />
<bo-loading-ring :variant="BoLoaderVariant.dark" loader-text="dark" />
<bo-loading-ring :variant="BoLoaderVariant.light" loader-text="light" />

Text positions

Adjust textPosition to control where the supporting text appears.

Top

Bottom

Before

After

<bo-loading-ring :text-position="BoLoaderTextPosition.top" loader-text="Top" />
<bo-loading-ring :text-position="BoLoaderTextPosition.bottom" loader-text="Bottom" />
<bo-loading-ring :text-position="BoLoaderTextPosition.before" loader-text="Before" />
<bo-loading-ring :text-position="BoLoaderTextPosition.after" loader-text="After" />

Custom text

Provide richer markup via the default slot. The slot replaces the loaderText prop entirely, allowing typography or iconography.

<bo-loading-ring>
	<span>Syncing files…</span>
</bo-loading-ring>

Syncing files…

Custom colors

You can customize the color of the ring by passing a valid CSS color value to the customColor prop.

CSS Variable

Hex Color

RGB Color

OKLCH Color

<bo-loading-ring custom-color="--teal-500" loader-text="CSS Variable" />
<bo-loading-ring custom-color="#ff6b6b" loader-text="Hex Color" />
<bo-loading-ring custom-color="rgb(255, 107, 107)" loader-text="RGB Color" />
<bo-loading-ring custom-color="oklch(0.7 0.15 180)" loader-text="OKLCH Color" />

Accessibility

• aria-live can be set to polite, assertive, or off for screen reader announcements
• aria-busy can be set to true while the ring is visible, signalling assistive tech that the region is updating
• aria-label provides accessible messaging when no loaderText is provided
• The component automatically generates unique IDs for testing and accessibility

Interfaces and constants

bo-loading-ring.ts

export interface BoLoaderRingProps {
	/** Unique id for the loader ring */
	id?: string
	/** Unique data-test-id for the loader ring container */
	dataTestId?: string
	/** The size of the loader ring */
	size?: BoSize
	/** Predefined color variant of the loader ring */
	variant?: BoLoaderVariant
	/** Optional loader text to display */
	loaderText?: string
	/** Position of the text relative to the loader ring */
	textPosition?: BoLoaderTextPosition
	/** Custom color of the loader ring in CSS compatible format */
	customColor?: string
	/** Accessibility live region politeness setting */
	ariaLive?: AriaLive
	/** Accessible label describing the loader ring state */
	ariaLabel?: string
	/** Mark the region as busy while the loader ring is visible */
	ariaBusy?: boolean
	/** Optional custom classes appended to the loader ring wrapper */
	customContainerCssClass?: string
	/** Optional custom classes appended to the loader ring element */
	customRingClass?: string
}

shared/accessibility.ts

export enum AriaLive {
	polite = 'polite',
	assertive = 'assertive',
	off = 'off',
}

shared/loader.ts

export enum BoLoaderVariant {
	primary = 'primary',
	secondary = 'secondary',
	success = 'success',
	warning = 'warning',
	danger = 'danger',
	dark = 'dark',
	light = 'light',
}

export enum BoLoaderTextPosition {
	top = 'top',
	bottom = 'bottom',
	before = 'before',
	after = 'after',
}

shared/size.ts

export enum BoSize {
	extra_small = 'extra-small',
	small = 'small',
	default = 'default',
	large = 'large',
	extra_large = 'extra-large',
}