Loader | Calcite Design System

Loaders are used to visually communicate processing.

Overview

Loaders show that something is loading, computing, or processing with a spinning visual.

Loader type's can be set as "determinate" or "indeterminate". As a good UX practice, "determinate" should be used whenever it is possible to relay the loading percentage.

Sample

Component comparison

Loader and Progress are similar in purpose but differ in appearance.

Loader

This component

Best for representing processing time.

Use independently or as built-in functionality such as Button's loading property

Progress

Alternative

Best for compactly representing processing time and advancement towards completion.

Use adjacent to the top or bottom edge of other elements.

Best practices

Consider using Progress or custom skeleton states when multiple loading indicators are needed. Too many Loaders can overwhelm users.

Panel titled Best Reading Spots in Central Park with a Loader indicating the content is 65% loaded.

Do use Loaders with a type of determinate or determinate-value when processing percentage is known and updates reliably.

Panel titled Best Reading Spots in Central Park with a Loader that does not indicate loading process.

Do use Loaders with a type of indeterminate when the processing percentage is unknown or unpredictable. User trust can be diminished by inaccurate percentages such as those that stall, jump, or move backward.

Accessibility

Loader must have an accompanying label property to provide context to assistive technologies. Add a concise description so users are able to interpret why the Loader is present.

API reference

Properties

Property	Attribute	Description	Type	Default
inline	inline	When `true`, the component displays smaller.	`boolean`	`false`
labelrequired	label	Specifies an accessible label for the component.	`string`
scale	scale	Specifies the size of the component.	`Scale`	`"m"`
text	text	When not `inline`, displays text under the component's indicator.	`string`	`""`
type	type	Specifies the component type. Use `"indeterminate"` if finding actual progress value is impossible. Otherwise, use `"determinate"` to have the value indicate the progress or `"determinate-value"` to have the value label displayed along the progress.	`"indeterminate" \| "determinate" \| "determinate-value"`	`"indeterminate"`
value	value	The component's value. Valid only for `"determinate"` indicators. Percent complete of 100.	`number`	`0`

Styles

Name	Description
--calcite-loader-font-size	When `type` is not `"indeterminate"` or `inline`, specifies the font size of the loading percentage.
--calcite-loader-size	Specifies the component's width and height.
--calcite-loader-size-inline	deprecated in v3.0.0, removal target v6.0.0 - Use `--calcite-loader-size` instead. Specifies the width and height of the component when set to inline.
--calcite-loader-spacing	Specifies the the component's padding.
--calcite-loader-progress-color-inline	When `inline`, specifies the component's progress ring color.
--calcite-loader-text-spacing	When not `inline`, specifies the component's `text` margin.
--calcite-loader-text-weight	When not `inline` and `text` is provided, specifies the component's `text` font weight.
--calcite-loader-text-color	When not `inline` and `text` is provided, specifies the component's `text` color.
--calcite-loader-progress-color	When not `inline`, specifies the component's progress ring color.
--calcite-loader-track-color	Specifies the component's track color.

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`