# Skeleton

## Overview

A loading placeholder that mimics the shape and dimensions of content while it's being fetched. Use it to provide visual continuity and reduce perceived load time — never leave blank white space while content is loading.

---

## When to Use

- While data is being fetched asynchronously
- As a content placeholder in cards, tables, and profile areas
- For any content that takes more than ~300ms to appear

## When NOT to Use

- Full-page loading states — use a page-level skeleton layout instead of a single `Skeleton`.
- For error states — show an `<Alert>` or `<Empty>` after failure.
- Do not use spinner-only indicators when structural content (cards, tables) will appear — use Skeleton instead.

---

## Props

| Prop        | Type     | Description                                                                                     |
| ----------- | -------- | ----------------------------------------------------------------------------------------------- |
| `className` | `string` | **Required** — sets width, height, and shape. The component renders nothing visible without it. |

---

## Examples

### Card Loading Skeleton

```tsx
import { Skeleton, Card, CardContent, CardHeader } from 'xertica-ui/ui';

<Card>
  <CardHeader>
    <Skeleton className="h-5 w-[200px]" />
    <Skeleton className="h-4 w-[150px] mt-2" />
  </CardHeader>
  <CardContent className="space-y-3">
    <Skeleton className="h-4 w-full" />
    <Skeleton className="h-4 w-full" />
    <Skeleton className="h-4 w-4/5" />
  </CardContent>
</Card>;
```

### Profile Skeleton

```tsx
<div className="flex items-center space-x-4">
  <Skeleton className="h-12 w-12 rounded-full" />
  <div className="space-y-2">
    <Skeleton className="h-4 w-[200px]" />
    <Skeleton className="h-4 w-[150px]" />
  </div>
</div>
```

### Table Row Skeletons

```tsx
{
  isLoading
    ? Array.from({ length: 5 }).map((_, i) => (
        <TableRow key={i}>
          <TableCell>
            <Skeleton className="h-4 w-[100px]" />
          </TableCell>
          <TableCell>
            <Skeleton className="h-4 w-[150px]" />
          </TableCell>
          <TableCell>
            <Skeleton className="h-4 w-[80px]" />
          </TableCell>
        </TableRow>
      ))
    : records.map(record => <RecordRow key={record.id} record={record} />);
}
```

---

## AI Rules

- **Always specify dimensions** via `className` — `Skeleton` renders as a pulse animation box sized by what you give it.
- For avatar/circle placeholders: `className="h-12 w-12 rounded-full"`.
- For text lines: `className="h-4 w-full"` or any width fraction (`w-3/4`, `w-1/2`).
- Always match the approximate shape of the content it replaces (same height, similar width).

---

## Related Components

- [`Empty`](./empty.md) — For zero-state views (after loading completes with no results)
- [`Card`](./card.md) — Most common Skeleton context