# ImagePlaceholder

> The shared foundation for a fixed-size image-with-fallback box — a user avatar, a brand logo, or any other picture that needs a graceful stand-in before it loads or when it's missing.

```ts
import { ImagePlaceholder } from "@sdxc/ui";
```

Renders the placeholder host: a fixed-size, centered box whose `data-shape`
attribute styles it, its image, and its fallback together, leaving room
for ImagePlaceholder.Badge to sit unclipped on the corner.

## Examples

```tsx
<ImagePlaceholder>
	<ImagePlaceholder.Image src={user.avatarUrl} alt={user.name} />
	<ImagePlaceholder.Fallback>{initials}</ImagePlaceholder.Fallback>
</ImagePlaceholder>
```

```tsx
<ImagePlaceholder size="lg" shape="square">
	<ImagePlaceholder.Image src={org.logoUrl} alt={org.name} />
	<ImagePlaceholder.Badge />
</ImagePlaceholder>
```

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | Size variant. Defaults to DEFAULT_SIZE. |
| `shape?` | `"circle" \| "square"` | Shape variant. Defaults to DEFAULT_SHAPE. |
| `children` | `RemixNode` | The host's compound parts: ImagePlaceholder.Image, ImagePlaceholder.Fallback, and an optional ImagePlaceholder.Badge. |

Also accepts everything in `TagProps<"span">`.


### ImagePlaceholder.Image

Renders the placeholder's image layer: an `<img>` cropped to cover, clipped to ImagePlaceholder's `data-shape`, its inset hairline holding the edge on a same-tone background.

| Prop | Type | Description |
| --- | --- | --- |
| `src` | `string` | Image source URL. |
| `alt` | `string` | Accessible text description of the image. Required, since a consumer's own localized description drives what assistive technology announces. |

Also accepts everything in `Omit<
		TagProps<"img">,
		"src" | "alt" | "role" | "aria-label" | "aria-labelledby" | "title"
	>`.


### ImagePlaceholder.Fallback

Renders the placeholder's fallback layer: a `<span>` centering a consumer's content in uppercase text.

| Prop | Type | Description |
| --- | --- | --- |
| `children` | `RemixNode` | Fallback content, typically the subject's initials. |

Also accepts everything in `TagProps<"span">`.


### ImagePlaceholder.Badge

Renders a small status dot pinned to the host's block-end/inline-end corner, always fully rounded regardless of ImagePlaceholder's own shape, and ringed to read as cut from whatever sits beneath it.

Also accepts everything in `TagProps<"span">`.


### ImagePlaceholder.Group

Renders a row of overlapping placeholders: a flex container that pulls each child back over the previous one and rings each in the neutral tint background, so the overlap reads as stacked cutouts.

| Prop | Type | Description |
| --- | --- | --- |
| `children` | `RemixNode` | A run of ImagePlaceholder instances, optionally trailed by ImagePlaceholder.GroupCount. |

Also accepts everything in `TagProps<"div">`.


### ImagePlaceholder.GroupCount

Renders the "+N" overflow indicator trailing ImagePlaceholder.Group: a medium box matching ImagePlaceholder's size, ring and `shape`, its tabular digits keeping a changing count the same width.

| Prop | Type | Description |
| --- | --- | --- |
| `shape?` | `"circle" \| "square"` | Shape variant, matching the shape of the sibling placeholders it trails. Defaults to DEFAULT_SHAPE. |
| `children` | `RemixNode` | The overflow count text, e.g. `"+3"`. |

Also accepts everything in `TagProps<"span">`.


## Types

| Name | Values | What it decides |
| --- | --- | --- |
| `Size` | `"sm" \| "md" \| "lg"` | Size variant controlling the host's rendered dimensions and, through ordinary inheritance, the fallback initials' font size. |
| `Shape` | `"circle" \| "square"` | Shape variant controlling the corner rounding of the host, its image, and its fallback layer: `"circle"` renders a fully rounded disc, and `"square"` renders a softly rounded square. |