Best Practices

Components

Skeleton: use only while the entire page loads and for up to 5s.
Custom loading state: use animations, illustrations, or progress bars for a process that takes more than 5s or when the content that will load has an irregular shape, such as a graph.
- If a process takes more than 5s, it's recommended to include the option to cancel the task and also the option to leave the page without interrupting the process.
- When it's not possible to design and implement a custom loading state, use a Spinner and include a short text below it or to its right explaining what is happening.
Don’t show any loading feedback for processes that take less than 1s.

When the Spinner is next to a text, replacing a text, or on top of a colored background, its color should use a foreground token from the same surface. For example, a Spinner on top of bg-muted should use fg-muted.
If the background color is strong (color-8 or higher), the Spinner should be fg-inverted. For example, use a white Spinner if the background color is blue-8.

When a trigger is pressed, and the Spinner is used to provide immediate feedback, position it as closely as possible to the trigger. For example, use the loading state of the Button.
Don’t customize the default size of the spinner.

A Spinner should only be used to provide feedback on processes that take between 1s and 5s.

A Spinner has a default spinning circle animation played in a loop that should not be customized.

When search results are loading, the loading state of the Search Input should be the only feedback. Maintain the previous results visible in the list until the new ones finish loading.
When a process takes more than 2s and less than 5s, content that might be modified should be completely hidden and temporarily replaced with loading feedback such as a Spinner.

It's not recommended to include text explaining a Spinner, since it's not recommended to use a Spinner for processes that take more than 5s.
When it's not possible to design and implement a custom loading state, a Spinner can be used - with a short text below it or to its right explaining what is happening. For example, the Spinner could be next to the word Indexing or to the text “This release is being published and may take up to 5 minutes”.