# Core/Spinner - Design

The Spinner component is used to display a loading state. It can be used in two modes: **Mode 1 - Standalone Spinner:**

<p>
  A spinner is a visual indicator of an ongoing, user-initiated process.
</p>

## Modes

### Replacement Mode

<p>
  Use Replacement Mode when you want to completely hide content while loading and show the spinner instead. This is ideal for initial page loads, route transitions, or when fetching data that's required before any content can be displayed. The content and spinner never appear simultaneously—the component returns early with just the spinner when loading.
</p>

<p>
  This mode is best for scenarios where showing partial or stale content would be confusing or misleading to users.
</p>

<p>
  <pre>
    ```tsx
    if (isLoading) {
      return <Spinner title="Loading..." />;
    }
    return <div>Content</div>;
    ```
  </pre>
</p>

### Overlay Mode

<p>
  Use Overlay Mode when you want to keep content visible while indicating an ongoing operation. The spinner appears
  as an overlay, allowing users to see what they're waiting for or maintain context during the loading process. This
  is perfect for refreshing data, submitting forms, or updating specific sections of a page.
</p>

<p>
  This mode works well for progressive enhancement scenarios, search results that are being refined, or any
  situation where the existing content provides value even during loading. It's particularly useful when you want to
  prevent user interaction temporarily without completely removing the content from view, such as during a save
  operation or background data synchronization.
</p>

<p>
  <pre>
    ```tsx
    <Spinner title="Loading..." isPending={isLoading}>
      <div>Content will be shown always</div>
      <div>Will be blurred if the spinner is visible</div>
    </Spinner>
    ```
  </pre>
</p>

## Properties

### Label

<p>
  A label can be added to the spinner to better inform users during a loading process. Common situations in which
  they are used include navigating to a page that is not fully known beforehand (e.g., a dashboard), or loading a
  large set of data.
</p>

### Sizes

<p>
  Small spinners are used when in cards or other inline components. Medium spinners are the default and are
  displayed when it represents a larger portion of the page, such as a primary data table. The large size can be
  used when all, or most, of the page content is being loaded.
</p>

## Accessibility

### Keyboard interaction

<p>
  A spinner is not a focusable element.
</p>

### Labeling

<p>
  When possible, supplement spinners with textual indicators to clarify the purpose and state.
</p>

### Focus order

<p>
  If the spinner is a blocking interaction, make sure to return focus to a relevant action once loading is complete.
</p>

### Aria considerations

* Use `aria-live="polite"` to enable screen readers to notify users of the loading state.
* When the loading state ends, remove the spinner from the DOM or hide it with `aria-hidden="true"`.