# Skeleton

Holds the place of content while it loads.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Skeleton.tsx)

## Overview

Skeleton renders a loading placeholder at the size of the content it wraps.

## Examples

### Basic

```tsx
import { Skeleton, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      <div {...styles.column()}>
        <Skeleton style={{ height: 14, width: 160 }} />
        <Skeleton style={{ height: 14, width: 96 }} />
      </div>
      <Skeleton>
        <p {...styles.text()}>Keeps the size of its content</p>
      </Skeleton>
    </div>
  )
}

namespace styles {
  export const column = style({ display: 'flex', flexDirection: 'column', gap: '8' })

  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '16' })

  export const text = style({ margin: '0', typography: 'body.b2' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Skeleton/Basic.tsx)

### Shape

Set `shape` to `default` (default), `pill`, or `circle`.

```tsx
import { Skeleton, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      <Skeleton shape="circle" style={{ height: 40, width: 40 }} />
      <Skeleton shape="default" style={{ height: 14, width: 160 }} />
      <Skeleton shape="pill" style={{ height: 32, width: 96 }} />
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '16' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Skeleton/Shape.tsx)

### Show

Set `show={false}` when data arrives to reveal the content. `show` defaults to `true`.

```tsx
import { Skeleton, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      <Skeleton>
        <p {...styles.text()}>Loading content</p>
      </Skeleton>
      <Skeleton show={false}>
        <p {...styles.text()}>Loaded content</p>
      </Skeleton>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '16' })

  export const text = style({ margin: '0', typography: 'body.b2' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Skeleton/Show.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Skeleton } from '@tempoxyz/ds'

<Skeleton />
```

## Guidelines

### When to Use

* Hold the place of content with a known layout, such as balances, activity rows, or metric tiles.
* Fill table rows, cards, and lists on first load, with the expected or a typical item count.

### When Not to Use

* Use [Spinner](/docs/components/spinner) when the shape of the result is unknown, or for a busy control.
* Use [Progress](/docs/components/progress) for a long task with measurable work.
* Use `loading` on a [Button](/docs/components/button) while its action runs.
* Use [Empty](/docs/components/empty) when the request returns no records.

### Match the Final Content's Shape

* **`circle`:** Avatars, identicons, and token icons.
* **`pill`:** Pill-shaped controls, such as an extra-small button.
* **`default`:** Text, blocks, badges, and buttons.

For a list, repeat each row's structure instead of one block.

**Do:** Mirror each row's icon, text lines, and amount.

```tsx
/**
 * Do example for "Match the Final Content's Shape" on the Skeleton page.
 * Mirror each row's icon, text lines, and amount.
 * @module
 */
import { Skeleton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      {['0x8f3c…a21b', '0x41d2…9c07', '0xb7e0…3f5a'].map((address) => (
        <div {...styles.row()} key={address}>
          <Skeleton shape="circle" style={{ height: 32, width: 32 }} />
          <div {...styles.text()}>
            <Skeleton>
              <div {...styles.title()}>{address}</div>
            </Skeleton>
            <Skeleton>
              <div {...styles.meta()}>Oct 18, 14:02</div>
            </Skeleton>
          </div>
          <Skeleton>
            <div {...styles.title()}>+50.00 USDC</div>
          </Skeleton>
        </div>
      ))}
    </div>
  )
}

namespace styles {
  export const list = style({ display: 'flex', flexDirection: 'column', gap: '16' })

  export const meta = style({ typography: 'body.b3' })

  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })

  export const text = style({
    alignItems: 'flex-start',
    display: 'flex',
    flex: '1 !custom',
    flexDirection: 'column',
    gap: '4',
  })

  export const title = style({ typography: 'body.b2' })
}
```

**Don't:** Cover a list with one block that hides its structure.

```tsx
/**
 * Don't example for "Match the Final Content's Shape" on the Skeleton page.
 * Don't cover a list with one block that hides its structure.
 * @module
 */
import { Skeleton } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return <Skeleton style={{ height: 144, width: 256 }} />
}
```

### Wrap the Real Content

Skeleton takes the size of its children and hides them with `visibility: hidden`. Set `show={false}` when the data arrives, so the content keeps its place in reading order.

```tsx
<Skeleton show={loading}>
  <Amount currency="USD" value={balance} />
</Skeleton>
```

Size an empty skeleton with `style` only when there is nothing to wrap.

**Do:** Wrap the element that holds the data, with a placeholder of typical length.

```tsx
/**
 * Do example for "Wrap the Real Content" on the Skeleton page.
 * Wrap the element that holds the data, with a placeholder of typical length.
 * @module
 */
import { Skeleton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.card()}>
      <div {...styles.label()}>Balance</div>
      <Skeleton>
        <div {...styles.value()}>1,250.00 USDC</div>
      </Skeleton>
    </div>
  )
}

namespace styles {
  export const card = style({
    alignItems: 'flex-start',
    display: 'flex',
    flexDirection: 'column',
    gap: '4',
  })

  export const label = style({ color: 'content.secondary', typography: 'body.b3' })

  export const value = style({ color: 'content.primary', typography: 'heading.h1' })
}
```

**Don't:** Swap in a separately sized block that doesn't match the content.

```tsx
/**
 * Don't example for "Wrap the Real Content" on the Skeleton page.
 * Don't swap in a separately sized block that doesn't match the content.
 * @module
 */
import { Skeleton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.card()}>
      <div {...styles.label()}>Balance</div>
      <Skeleton style={{ height: 12, width: 80 }} />
    </div>
  )
}

namespace styles {
  export const card = style({
    alignItems: 'flex-start',
    display: 'flex',
    flexDirection: 'column',
    gap: '4',
  })

  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
}
```

### Keep Labels and Controls Visible

Keep headings, labels, tabs, filters, and buttons that do not depend on the data on screen.

**Do:** Keep the label and actions, and hold the place of the amount.

```tsx
/**
 * Do example for "Keep Labels and Controls Visible" on the Skeleton page.
 * Keep the label and actions, and hold the place of the amount.
 * @module
 */
import { Button, Skeleton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.card()}>
      <div {...styles.label()}>Balance</div>
      <Skeleton>
        <div {...styles.value()}>$1,250.00</div>
      </Skeleton>
      <div {...styles.actions()}>
        <Button size="small">Send</Button>
        <Button size="small" variant="secondary">
          Receive
        </Button>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({ display: 'flex', gap: '8', marginBlockStart: '12' })

  export const card = style({
    alignItems: 'flex-start',
    display: 'flex',
    flexDirection: 'column',
    gap: '4',
  })

  export const label = style({ color: 'content.secondary', typography: 'body.b3' })

  export const value = style({ color: 'content.primary', typography: 'heading.h1' })
}
```

**Don't:** Turn static labels and buttons into skeletons.

```tsx
/**
 * Don't example for "Keep Labels and Controls Visible" on the Skeleton page.
 * Don't turn static labels and buttons into skeletons.
 * @module
 */
import { Button, Skeleton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.card()}>
      <Skeleton>
        <div {...styles.label()}>Balance</div>
      </Skeleton>
      <Skeleton>
        <div {...styles.value()}>$1,250.00</div>
      </Skeleton>
      <div {...styles.actions()}>
        <Skeleton shape="pill">
          <Button size="small">Send</Button>
        </Skeleton>
        <Skeleton shape="pill">
          <Button size="small" variant="secondary">
            Receive
          </Button>
        </Skeleton>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({ display: 'flex', gap: '8', marginBlockStart: '12' })

  export const card = style({
    alignItems: 'flex-start',
    display: 'flex',
    flexDirection: 'column',
    gap: '4',
  })

  export const label = style({ color: 'content.secondary', typography: 'body.b3' })

  export const value = style({ color: 'content.primary', typography: 'heading.h1' })
}
```

### Keep Current Data During a Refresh

**Do:** Keep values on screen, such as a polled balance, until the new ones arrive.

```tsx
/**
 * Do example for "Keep Current Data During a Refresh" on the Skeleton page.
 * Keep values on screen, such as a polled balance, until the new ones arrive.
 * @module
 */
import { style } from '@tempoxyz/ds'

const payments = [
  { address: '0x8f3c…a21b', amount: '+50.00 USDC' },
  { address: '0x41d2…9c07', amount: '-25.00 USDC' },
]

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <div {...styles.heading()}>Activity</div>
      {payments.map((payment) => (
        <div {...styles.row()} key={payment.address}>
          <div>{payment.address}</div>
          <div>{payment.amount}</div>
        </div>
      ))}
    </div>
  )
}

namespace styles {
  export const heading = style({ color: 'content.primary', typography: 'body.b2Strong' })

  export const list = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '12',
    width: '100% !custom',
  })

  export const row = style({
    alignItems: 'center',
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'body.b2',
  })
}
```

**Don't:** Return to skeletons on every refresh.

```tsx
/**
 * Don't example for "Keep Current Data During a Refresh" on the Skeleton page.
 * Don't return to skeletons on every refresh.
 * @module
 */
import { Skeleton, style } from '@tempoxyz/ds'

const payments = [
  { address: '0x8f3c…a21b', amount: '+50.00 USDC' },
  { address: '0x41d2…9c07', amount: '-25.00 USDC' },
]

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <div {...styles.heading()}>Activity</div>
      {payments.map((payment) => (
        <div {...styles.row()} key={payment.address}>
          <Skeleton>
            <div>{payment.address}</div>
          </Skeleton>
          <Skeleton>
            <div>{payment.amount}</div>
          </Skeleton>
        </div>
      ))}
    </div>
  )
}

namespace styles {
  export const heading = style({ color: 'content.primary', typography: 'body.b2Strong' })

  export const list = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '12',
    width: '100% !custom',
  })

  export const row = style({
    alignItems: 'center',
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'body.b2',
  })
}
```

### Skip It for Fast Responses

* **Fast Responses (Under 300 ms):** Delay the skeleton, so the content renders without a flash.
* **Typical Waits (300 ms to 10 s):** Show the skeleton.
* **Long Waits (Over 10 s):** Show [Progress](/docs/components/progress). See [Loading](/docs/patterns/loading).

## Accessibility

Skeleton renders a `div` that marks its content busy and hides it until `show={false}`. It has no live region, and most screen readers ignore `aria-busy` on a plain `div`.

### Semantics

* **Busy State (aria-busy):** Marks the region busy while `show` is true.
* **Hidden Content (visibility: hidden):** Screen readers skip the placeholder text, and focus cannot reach hidden controls.
* **Pointer Events:** The root blocks pointer events while it shows, so placeholder buttons are inert.
* **Reduced Motion (prefers-reduced-motion):** The sweep stops, and the placeholder stays a static tint.

### Your Responsibilities

* **Announce Long Loads (status):** For main content, state what loads in a status message, such as "Loading activity".
* **Handle Failures:** If loading fails, show an error message. Never leave a skeleton that does not resolve.

## Related

[Spinner](/docs/components/spinner)

Use for loading with an unknown shape.

[Progress](/docs/components/progress)

Use for measurable work.

[Empty](/docs/components/empty)

Use for a region with nothing to show.

[Loading](/docs/patterns/loading)

Covers choosing a loading indicator.
