Spinner

What is this?

Spinner indicators allow merchants to identify that an element in the page is loading or that a task is in progress.

Examples

Contextual theming

The spinner's circle always has the currentColor fill.

Size

Alternatives

Skeleton - For layout/block loading

Usage

import { Spinner } from '@vtex/admin-ui'

function Example() {
  return <Spinner />
}

Props

It also accepts all the props of svg jsx element.

Name	Type	Description	Required	Default
size	number	Spinner size in px	🚫	24

Components

When to use a Skeleton or a custom loading state instead of a Spinner?

• Choose a Skeleton when the entire page is loading for up to 5 seconds.
• Choose a custom loading state with animations, illustrations, or progress bars to provide feedback on a process that takes more than 5 seconds or when the content that will load has an irregular shape, such as a graph.

What to avoid:

• Don’t show any loading feedback for requests that take less than a second.
• Don’t show a Skeleton on a page that is already loaded.

Variants

What should be the color of a Spinner?

• In most cases, a Spinner should have a gray ($fg.secondary) color.
• When the Spinner is replacing a text of a different color or displayed on top of a colorful background, its color should use a foreground token in the same tone. For example, when a secondary critical Button is loading it should use a red Spinner.
• If the background color is 40 or higher, the Spinner should be white. For example, if the background color is blue40, use a white Spinner.

Position

What should be the size and position of a Spinner in a container?

• When the Spinner provides immediate feedback of an action, it should be positioned as closely as possible to the trigger that the merchant pressed. For example, the loading state of the Button component can be used.
• If the process takes less than 2s, any content that might be modified should stay visible until the new content loads to avoid a sudden transition. When the process takes between 2s and 5s, the content that might be modified can also be temporarily replaced by a loading state.
• When a process takes more than 5s, use a custom loading state with animations, illustrations, or progress bars instead of a Spinner. If this is not possible and a Spinner will be used, make sure to include explanatory text below the Spinner or to its right.
• When a Spinner is positioned inside a small container or replacing a specific string of text, it should have a 20px size. When the Spinner is centralized in a large container, it should have a 40px size.
• When search results are loading, the Spinner in the Search Input loading state should be the only feedback. The previous results should remain visible in the list until the new ones finish loading.

What to avoid:

• Don’t overlay a Spinner on top of existing content. Prefer hiding the content.
• Don’t use a Spinner in a size that is not 20px or 40px.

Behavior

What should be the duration of a Spinner?

• A Spinner should be used to provide feedback on processes that take between 1s and 5s.
• When a process takes more than 5s, use a custom loading state with animations, illustrations, or progress bars instead of a Spinner. If this is not possible and a Spinner will be used, make sure to include explanatory text below the Spinner or to its right. Also allow the merchant to both cancel the task and to leave the page without interrupting the process.

What to avoid:

• Don’t display any sort of feedback when loading takes less than a second.

What should be the animation of a Spinner?

Spinner indicators have a default spinning circle animation that is played in a loop. Don’t customize this animation.

When should the content be hidden by a Spinner?

• If the process takes less than 2s, any content that might be modified should stay visible until the new content loads to avoid a sudden transition. When the process takes between 2s and 5s, the content that might be modified can also be temporarily replaced by a loading state.
• When search results are loading, the Spinner in the Search Input loading state should be the only feedback. The previous results should remain visible in the list until the new ones finish loading.

What to avoid:

• Don’t overlay a Spinner on top of existing content. Prefer hiding the content.

Variants

What should be the explanation of a Spinner?

• Don't include text to explain a process that takes less than 5s. When a process takes more than 5s, use a custom loading state with animations, illustrations, or progress bars instead of a Spinner.
• If it is not possible to design and implement a custom loading state and a Spinner will be used, make sure to include the explanatory text below the Spinner or to its right.
• The explanation should mention what is happening in the background and include an estimated duration for the process. 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”.
• Whenever a process takes more than 5s, allow the merchant to both cancel the task and to leave the page without interrupting the process.

• What is this?