# Motion and Loading

Source: https://payloadcms.com/docs/beta/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

Inside a Payload Admin Panel Custom Component:

```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 animationDuration="160ms" show={show} />
```

**Styling**

Override LoadingOverlay tokens to customize its backdrop and spinner while preserving the built-in loading behavior.

```css
@layer payload {
  .loading-overlay {
    --color-bg: #f8f7fc;
    --color-icon-secondary: #6d5dfc;
  }
}
```

- `--color-bg`: Loading backdrop color.
- `--color-icon-secondary`: Spinner color.

`LoadingOverlay` renders a spinner and backdrop 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 ShimmerEffect tokens on the component to match a custom surface without changing global background colors.

```css
@layer payload {
  .shimmer-effect {
    --shine-bg: #ebe9f5;
    --shine-fg: #f8f7fc;
    --radius-medium: 0.5rem;
  }
}
```

- `--shine-bg`: Base placeholder color.
- `--shine-fg`: Animated highlight color.
- `--radius-medium`: Default placeholder 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 progress element to replace its default text-colored fill with a semantic brand color.

```css
@layer payload {
  .progress-bar__progress {
    background-color: var(--color-bg-brand);
  }
}
```

- `--color-bg-brand`: Route progress fill color in this override.

`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 brief route transition so the delayed progress indicator remains visible long enough to inspect.

## Other helpers

- [`AnimateHeight`](/docs/v4/ui-components/animate-height.md) animates a container when its content changes height.
- [`ShimmerEffect`](/docs/v4/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. |
| `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.            |

### 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.