# Motion and Loading

Source: https://payloadcms.com/docs/ui-components/motion-and-loading

Payload's loading components communicate that work is in progress, while its motion helpers make layout changes easier to follow.

## Import

```tsx
import {
  AnimateHeight,
  FormLoadingOverlayToggle,
  LoadingOverlay,
  LoadingOverlayToggle,
  ProgressBar,
  ShimmerEffect,
  StaggeredShimmers,
} from '@payloadcms/ui'
```

## Loading overlay

**Implementation**

```tsx
const [show, setShow] = useState(false)

<Button onClick={() => setShow(true)}>Show loading overlay</Button>
<LoadingOverlay loadingText="Loading" show={show} />
```

**Styling**

Change the loading veil and animated bars without altering the overlay’s timing or accessibility behavior.

```css
.loading-overlay::after {
  background: #151225;
  opacity: 0.9;
}

.loading-overlay__bar {
  background: #8b7cf6;
}
```

- `background`: Overlay veil or loading-bar color.
- `opacity`: Strength of the overlay veil.

`LoadingOverlay` renders the visual loading surface directly. Use `LoadingOverlayToggle` inside the Admin Panel to update Payload's shared loading overlay instead.

`FormLoadingOverlayToggle` connects that shared overlay to a Payload form's loading and processing states. It must be rendered inside the Admin Panel's form and loading providers.

## Staggered shimmers

**Implementation**

```tsx
<StaggeredShimmers
  count={4}
  height={12}
  renderDelay={0}
  shimmerDelay={75}
/>
```

**Styling**

Override the ShimmerEffect variables to match a branded loading surface without changing the animation implementation.

```css
.shimmer-effect {
  --shine-bg: #ebe7ff;
  --shine-fg: #b8adff;
  border-radius: 6px;
}
```

- `--shine-bg`: Resting skeleton background.
- `--shine-fg`: Animated highlight color.
- `border-radius`: Skeleton corner radius.

Use `ShimmerEffect` for one placeholder or `StaggeredShimmers` for a repeated set. Match their dimensions to the content they temporarily replace to reduce layout movement.

## Route progress

**Implementation**

```tsx
<RouteTransitionProvider>
  <ProgressBar />
  <Link href="/admin/collections/posts">View posts</Link>
</RouteTransitionProvider>
```

**Styling**

Target the ProgressBar track height and progress element to create a more visible branded route transition.

```css
.progress-bar {
  height: 4px;
}

.progress-bar__progress {
  background: #6d5dfc;
}
```

- `background`: Progress indicator color.
- `height`: Progress indicator thickness.

`ProgressBar` displays progress for transitions started within `RouteTransitionProvider`. Payload's `Link` component starts this transition automatically. Use `startRouteTransition` from `useRouteTransition` when navigation begins from another control.

The preview simulates a slower route so the delayed progress indicator remains visible long enough to inspect.

## Other helpers

- [`AnimateHeight`](/docs/v3/ui-components/animate-height.md) animates a container when its content changes height.
- [`ShimmerEffect`](/docs/v3/ui-components/shimmer-effect.md) documents the single-placeholder API in more detail.

## Common props

These are the props most commonly used. See the exported types in `@payloadcms/ui` for the complete list.

### LoadingOverlay

| Prop                | Type      | Default   | Description                                      |
| ------------------- | --------- | --------- | ------------------------------------------------ |
| `show`              | `boolean` | `true`    | Selects the entering or exiting animation state. |
| `loadingText`       | `string`  | —         | Replaces the translated loading label.           |
| `animationDuration` | `string`  | `'500ms'` | Sets the CSS animation duration.                 |
| `overlayType`       | `string`  | —         | Adds a type modifier to the overlay.             |

### LoadingOverlayToggle

| Prop          | Type                           | Default        | Description                                   |
| ------------- | ------------------------------ | -------------- | --------------------------------------------- |
| `name` \*     | `string`                       | —              | Identifies this source in the shared overlay. |
| `show` \*     | `boolean`                      | —              | Adds or removes this source's loading state.  |
| `type`        | `'fullscreen' \| 'withoutNav'` | `'fullscreen'` | Selects the shared overlay layout.            |
| `loadingText` | `string`                       | —              | Replaces the translated loading label.        |

### StaggeredShimmers

| Prop           | Type               | Default | Description                                      |
| -------------- | ------------------ | ------- | ------------------------------------------------ |
| `count` \*     | `number`           | —       | Sets the number of shimmer placeholders.         |
| `height`       | `number \| string` | —       | Sets each placeholder's height.                  |
| `width`        | `number \| string` | —       | Sets each placeholder's width.                   |
| `renderDelay`  | `number`           | `500`   | Delays rendering to avoid flashing on fast work. |
| `shimmerDelay` | `number \| string` | `25`    | Staggers the animation between placeholders.     |

_\* An asterisk denotes that a prop is required._

## Accessibility

Loading visuals should accompany, not replace, meaningful status text. Prevent interaction when an action cannot safely continue, and keep the loading state visible only while work is actually pending.