OpenParable
Skip to content
← Back to skills

Loading UX

Development
loading-ux

Loading UX is an Agent Skill for development published in the toss/suspensive repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Loading UX without flash-of-loading in @suspensive/react: Suspense fallback, Delay (ms, fallback, isDelayed render prop) to hold back spinners and fade skeletons in, DefaultPropsProvider + new DefaultProps for app-wide default fallbacks. Load when writing Suspense fallbacks, skeletons, spinners, or global loading defaults.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/toss/suspensive/blob/HEAD/packages/react/skills/react/loading-ux/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/loading-ux, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Loading UX with Suspense, Delay, and DefaultPropsProvider

This skill builds on react. Read ../SKILL.md first for the client-only constraint and the .with() HOC pattern.

Setup

'use client'
import { Delay, Suspense } from '@suspensive/react'
import { Content } from './Content'
import { Spinner } from './Spinner'

export const Example = () => (
  <Suspense
    fallback={
      <Delay ms={200}>
        <Spinner />
      </Delay>
    }
  >
    <Content />
  </Suspense>
)

Delay postpones exposing its children by ms — if Content resolves within 200ms, the user never sees the spinner. Recommended ms: 100–300 for most UI, 500+ for non-critical sections.

DelayProps is a union: either { ms?, fallback?: ReactNode, children?: ReactNode } or { ms?, children?: ({ isDelayed }) => ReactNode } (no fallback allowed with a render-prop child).

Core Patterns

Fade the skeleton in with the isDelayed render prop

'use client'
import { Delay, Suspense } from '@suspensive/react'
import { Content } from './Content'
import { Skeleton } from './Skeleton'

export const Example = () => (
  <Suspense
    fallback={
      <Delay ms={200}>
        {({ isDelayed }) => <Skeleton style={{ opacity: isDelayed ? 1 : 0, transition: 'opacity 200ms' }} />}
      </Delay>
    }
  >
    <Content />
  </Suspense>
)

When children is a render prop, Delay always renders it and flips isDelayed to true after ms, enabling opacity transitions instead of an abrupt pop-in (available since v3.12).

Show an interim fallback before the delayed children

'use client'
import { Delay } from '@suspensive/react'

export const Example = () => (
  <Delay ms={200} fallback={<>Almost there...</>}>
    200ms delayed content
  </Delay>
)

One default fallback for every Suspense and Delay in the app

'use client'
import { DefaultProps, DefaultPropsProvider, Suspense } from '@suspensive/react'
import { Page } from './Page'
import { Spinner } from './Spinner'

const defaultProps = new DefaultProps({
  Delay: { ms: 1200 },
  Suspense: { fallback: <Spinner />, clientOnly: false },
})

export const App = () => (
  <DefaultPropsProvider defaultProps={defaultProps}>
    <Suspense>
      <Page />
    </Suspense>
  </DefaultPropsProvider>
)

<Suspense> and <Delay> without explicit props read defaults from the nearest provider; per-component props always win.

Common Mistakes

MEDIUM Hand-rolling spinner delay with useState/useEffect/setTimeout

Wrong:

import { useEffect, useState } from 'react'

const DelayedSpinner = () => {
  const [show, setShow] = useState(false)
  useEffect(() => {
    const t = setTimeout(() => setShow(true), 200)
    return () => clearTimeout(t)
  }, [])
  return show ? <Spinner /> : null
}

Correct:

import { Delay, Suspense } from '@suspensive/react'

const Example = ({ children }) => (
  <Suspense
    fallback={
      <Delay ms={200}>
        <Spinner />
      </Delay>
    }
  >
    {children}
  </Suspense>
)

Delay does the timeout declaratively, composes inside any Suspense fallback, and picks up default ms from DefaultPropsProvider.

Source: docs/suspensive.org/src/content/en/docs/react/Delay.mdx

MEDIUM Passing a plain object to DefaultPropsProvider

Wrong:

import { DefaultPropsProvider } from '@suspensive/react'

const App = ({ children }) => (
  <DefaultPropsProvider defaultProps={{ Suspense: { fallback: <Spinner /> } }}>{children}</DefaultPropsProvider>
)

Correct:

import { DefaultProps, DefaultPropsProvider } from '@suspensive/react'

const defaultProps = new DefaultProps({ Suspense: { fallback: <Spinner /> } })

const App = ({ children }) => <DefaultPropsProvider defaultProps={defaultProps}>{children}</DefaultPropsProvider>

defaultProps must be an instance of the DefaultProps class; a plain object literal is not accepted.

Source: docs/suspensive.org/src/content/en/docs/react/DefaultPropsProvider.mdx

MEDIUM Abrupt skeleton-to-content swap instead of isDelayed fade

Wrong:

import { Delay } from '@suspensive/react'

// plus a separate hand-written fade-in component around Spinner
const Fallback = () => (
  <Delay ms={200}>
    <FadeIn>
      <Spinner />
    </FadeIn>
  </Delay>
)

Correct:

import { Delay } from '@suspensive/react'

const Fallback = () => (
  <Delay ms={200}>
    {({ isDelayed }) => <Spinner style={{ opacity: isDelayed ? 1 : 0, transition: 'opacity 200ms' }} />}
  </Delay>
)

The render-prop child receives isDelayed (v3.12+) exactly for this; agents unaware of it wire CSS animation components by hand.

Source: docs/suspensive.org/src/content/en/docs/react/Delay.mdx (#1312)

MEDIUM Reading Delay ms as extending fallback display time

Wrong:

import { Delay, Suspense } from '@suspensive/react'

// expecting the spinner to stay visible for at least 3s
const Example = ({ children }) => (
  <Suspense
    fallback={
      <Delay ms={3000}>
        <Spinner />
      </Delay>
    }
  >
    {children}
  </Suspense>
)

Correct:

import { Delay, Suspense } from '@suspensive/react'

// ms only postpones when the spinner APPEARS; content replaces it as soon as it resolves
const Example = ({ children }) => (
  <Suspense
    fallback={
      <Delay ms={200}>
        <Spinner />
      </Delay>
    }
  >
    {children}
  </Suspense>
)

Delay postpones exposing its children/fallback; it never prolongs how long a fallback stays visible — a 1s fetch with ms={3000} shows no spinner at all, not 4s of spinner.

Source: https://github.com/toss/suspensive/issues/182

See also: the declarative-queries skill in @suspensive/react-query-4/@suspensive/react-query-5 — Delay composes inside Suspense fallbacks that wrap SuspenseQuery.