image

Image

Responsive image wrapper with fallbacks.

Image Examples

Copy-ready examples with live previews.

Basic usage

Wrapper size is controlled by width + height.

Live preview

import Image from "@/_components/img/Image";

export default function Example() {
  return (
    <Image
      src="/images/image_placeholder.png"
      alt="Demo"
      width="360px"
      height="240px"
    />
  );
}

Variants

Visual variants map to CSS classes (rect / circle / large).

Live preview

variant="rect"

variant="circle"

variant="large"

import Image from "@/_components/img/Image";

export default function Example() {
  return (
    <>
      <Image src="/images/image_placeholder.png" alt="Rect" width="180px" height="120px" variant="rect" />
      <Image src="/images/image_placeholder.png" alt="Circle" width="130px" height="130px" variant="circle" />
      <Image src="/images/image_placeholder.png" alt="Large" width="240px" height="160px" variant="large" />
    </>
  );
}

Style flags

Helpers for elevated / disabled / inverted visuals.

Live preview

elevated

disabled

inverted

import Image from "@/_components/img/Image";

export default function Example() {
  return (
    <>
      <Image src="/images/image_placeholder.png" alt="Elevated" width="180px" height="120px" elevated />
      <Image src="/images/image_placeholder.png" alt="Disabled" width="180px" height="120px" disabled />
      <Image src="/images/image_placeholder.png" alt="Inverted" width="180px" height="120px" inverted />
    </>
  );
}

Auto loading / error states

When src is missing, the component immediately shows the error overlay (auto behavior).

Live preview

import { useState } from "react";
import Image from "@/packages/ui/src/_components/img/Image";
import { Button } from "@/packages/ui/src/_components/buttons_variants/buttons/Button";

const SRC = "/images/image_placeholder.png";

export default function Example() {
  const [src, setSrc] = useState<string | undefined>(SRC);

  return (
    <>
      <Button variant="primary" onClick={() => setSrc(SRC)}>Valid src</Button>
      <Button variant="secondary" onClick={() => setSrc(undefined)}>Missing src</Button>

      <Image src={src} alt="Demo" width="360px" height="240px" />
    </>
  );
}

Override states (loading / errorLoading)

Use these props to force overlays (they override internal auto states).

Live preview

Overrides take priority over the internal auto states.

import { useState } from "react";
import Image from "@/packages/ui/src/_components/img/Image";

export default function Example() {
  const [loading, setLoading] = useState<boolean | undefined>(true);
  const [errorLoading, setErrorLoading] = useState<boolean | undefined>(undefined);

  return (
    <Image
      src="/images/image_placeholder.png"
      alt="Demo"
      width="360px"
      height="240px"
      loading={loading}
      errorLoading={errorLoading}
    />
  );
}

Interactive playground

Quick way to validate combinations in docs.

Live preview

src

variant

flags

state overrides

import { useState } from "react";
import Image from "@/packages/ui/src/_components/img/Image";

type ImageVariant = "rect" | "circle" | "large" | undefined;

const SRC = "/images/image_placeholder.png";

export default function Example() {
  const [src, setSrc] = useState<string | undefined>(SRC);
  const [variant, setVariant] = useState<ImageVariant>(undefined);

  return (
    <Image
      src={src}
      alt="Demo"
      width="100%"
      height="300px"
      variant={variant}
    />
  );
}

On this page

Image Props

Image — Props
Prop	Type	Required	Default	Description
src	string	No	undefined	Image URL. If missing, the component goes into error state.
alt	string	No	""	Image alt text.
width	string	Yes	—	Wrapper width (e.g. "320px", "100%").
height	string	Yes	—	Wrapper height (e.g. "200px").
customStyles	React.CSSProperties	No	undefined	Extra inline styles applied to the wrapper.
variant	"rect" \| "circle" \| "large"	No	undefined	Visual variant (maps to CSS classes).
elevated	boolean	No	false	Adds an "elevated" style class.
disabled	boolean	No	false	Adds a disabled style class.
inverted	boolean	No	false	Applies an inverted style class (`is-inverted`).
loading	boolean	No	undefined	Overrides internal loading state. When true, the Shimmer overlay is shown.
errorLoading	boolean	No	undefined	Overrides internal error state. When true, the Error overlay is shown.