Placeholder

Overview

<Placeholder> renders an inline <svg> sized to width/height, filled with a context color and a {width}x{height} label — useful for mocking up layouts before real images exist. Pass src and it renders a real <img> instead (or any component passed via component), so the same component can point at a project's own default image, a placehold.co URL, or any other source once one is available — no need to swap components as content comes online.

• width and height size the graphic and (unless overridden) generate its default label text.
• color sets the generated graphic's background/foreground to one of the context colors. Has no effect when src is set.
• text and title override or hide (false) the generated graphic's label and accessible title. Have no effect when src is set.
• src switches to rendering a real image, forwarding any other native img props (alt, loading, srcSet, …) alongside it. Only applies when src is set: fluid (responsive, image fluid), thumbnail (image thumbnail), rounded, and align (start/center/end).
• component swaps the <img> rendered in src mode for any other element or component — see Using a custom image component.

Examples

Basic usage

With no other props, <Placeholder> renders a generated graphic sized to width/height.

import { Placeholder } from '@chassis-ui/react'

export const Example = () => {
  return <Placeholder width={320} height={160} />
}

Color

Pass color to set the generated graphic's background and foreground to one of the context colors.

import { Flex, Placeholder } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Flex gap={'sm'} wrap="wrap">
      <Placeholder color="default" width={140} height={100} />
      <Placeholder color="alternate" width={140} height={100} />
      <Placeholder color="primary" width={140} height={100} />
      <Placeholder color="secondary" width={140} height={100} />
      <Placeholder color="neutral" width={140} height={100} />
      <Placeholder color="success" width={140} height={100} />
      <Placeholder color="danger" width={140} height={100} />
      <Placeholder color="warning" width={140} height={100} />
      <Placeholder color="info" width={140} height={100} />
    </Flex>
  )
}

Custom text and title

text and title default to {width}x{height} and "Placeholder" respectively. Pass a string to override either, or false to hide it.

import { Flex, Placeholder } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Flex gap="md" wrap="wrap">
      <Placeholder width={200} height={120} title="Cover" text="No cover yet" />
      <Placeholder width={200} height={120} title={false} text="Coming soon" />
      <Placeholder width={200} height={120} text={false} />
    </Flex>
  )
}

Using a real image

Pass src (and alt) to render an actual image instead of the generated graphic — handy for swapping a mockup for a placehold.co URL, or a project's own default image, without changing components.

JSX

import { Placeholder } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Placeholder
      src="https://placehold.co/320x160"
      alt="A placeholder image served from placehold.co"
      width={320}
      height={160}
    />
  )
}

Styling a real image

fluid, thumbnail, rounded, and align only apply in src mode, mapping to chassis-css's .image.fluid, .image.thumbnail, .rounded, and float/centering utilities respectively.

JSX

import { Flex, Placeholder } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Flex gap="md" wrap="wrap" align="center">
      <Placeholder src="https://placehold.co/160x100" alt="" fluid />
      <Placeholder src="https://placehold.co/160x100" alt="" thumbnail />
      <Placeholder src="https://placehold.co/160x100" alt="" rounded />
    </Flex>
  )
}

Using a custom image component

<Placeholder> renders a plain <img> in src mode by default, but its component prop accepts any element or component — including a framework's own Image (Next.js, Gatsby, Remix, etc.). Whatever is passed is fully type-checked at the call site, so a component's own props (fill, priority, loader, and so on) are available and validated alongside src/alt:

import Image from 'next/image'

<Placeholder component={Image} src="/hero.jpg" alt="" fill priority />

From a React Server Component, where a component reference can't be passed as a prop, render the image as the child with asChild. The child carries its own src:

import Image from 'next/image'

<Placeholder asChild fluid rounded>
  <Image src="/hero.jpg" width={800} height={400} alt="" />
</Placeholder>

API

Placeholder