# Image placeholder

A flat block that stands where a picture will go, for empty states and mockups.

Block: `smbk-image-placeholder`. Status: candidate. Figma: the Figma file, https://www.figma.com/community/file/1688324308358870630. Desktop and mobile: differ by presentation only.

## Options

| Axis | Values | Default | Meaning |
|---|---|---|---|



## Markup

```html
<span class="smbk-image-placeholder" aria-hidden="true" style="aspect-ratio:16 / 9"></span>
```

## React

```tsx
import { ImagePlaceholder } from './design-system/components/image-placeholder/image-placeholder.js';

<ImagePlaceholder ratio={[16, 9]} />
```

## Stylesheet

```css
/* smbk-image-placeholder — Image placeholder. Figma "Image Placeholder" 1988:5921.
 * Takes the width it is given and the ratio of the picture it stands for: a
 * sunken block with a container's corner and a hairline edge, so it shows on
 * the page color. */

.smbk-image-placeholder {
  box-sizing: border-box;
  display: block;
  width: 100%;
  border: var(--smbk-border-width-hairline) solid var(--smbk-color-border-subtle);
  border-radius: var(--smbk-radius-container-sm);
  background: var(--smbk-color-surface-sunken);
}
```

## Tokens it reads

```json
{
  "border-width": {
    "hairline": {
      "$type": "dimension",
      "$value": "{{border-width.1}}",
      "$description": "Thin lines: dividers and almost every edge."
    }
  },
  "color": {
    "border": {
      "subtle": {
        "$type": "color",
        "$value": "{{color.grey.300}}",
        "$description": "Dividers and quiet edges."
      }
    },
    "surface": {
      "sunken": {
        "$type": "color",
        "$value": "{{color.alpha.grey-800.5}}",
        "$description": "Recessed wells: fields, tracks, code. See-through, so a well always shows one step below what it sits on: the page, a card or a panel."
      }
    }
  },
  "radius": {
    "container": {
      "sm": {
        "$type": "dimension",
        "$value": "{{radius.8}}",
        "$description": "Corners of cards, panels and dialogs, small."
      }
    }
  }
}
```

## Purpose

A flat, rounded block with a hairline edge, so it shows on the page color, that holds the place of a picture that is missing or not yet chosen: an empty avatar slot, a card without a cover, a mockup. It is a static state, which is what separates it from the skeleton, which stands in while something loads.

## Anatomy

One element. No parts.

## When to use

- A picture slot with nothing in it yet.
- Mockups and templates.

## When not to use

- While a picture is loading. Use the [skeleton](skeleton.md)'s media shape.

## Behavior

None.

## Accessibility

### What it does for you

- It is decorative unless given a label, in which case it is announced as an image with that name.

### What you must do

- Give it a label when it should be announced as an image.

### How to test

- With a screen reader, an unlabeled placeholder is skipped and a labeled one is read as an image by its label.

## Usage rules

### Do

- Give it the ratio of the picture it replaces, so nothing moves when the picture arrives.
- Size it through its container. It fills the container's width and takes its height from its ratio.