Skip to content
Components

GalleryImage

Gallery image that handles variant changes with crossfade. Shows old image + shimmer while new image loads, then crossfades. Framework-agnostic: uses a render prop to let you provide any image component.

Material sample

Usage

import { GalleryImage, ImageSkeleton, LoadingImage } from "@instruments/materia-ui/components/gallery";

Best practices

  • In Next.js pass a children render prop wrapping next/image and thread its src+className through - the default renderer is a plain <img> that skips Next optimisation.

  • When you omit children, alt is required (a dev warning fires otherwise); pass alt="" to mark the image decorative. alt is ignored once a render prop supplies its own image.

  • Drive variant switches by changing src - that triggers the built-in crossfade + shimmer; don't unmount/remount GalleryImage per variant or you lose the transition.

  • Position GalleryImage inside a relative container with fixed dimensions - the surfaces are absolute inset-0, so an unsized parent collapses to zero height.

Props

GalleryImage

PropTypeDefaultDescription
altstring

Alt text for the built-in <img> renderer used when children is omitted. Required in that mode (a dev-only warning fires otherwise); pass "" to mark the image decorative. Ignored when children is provided.

children(props: ImageRenderProps) => ReactNode

Render function that receives props to spread onto your image component. Must pass src and className to the rendered image surface. When omitted, GalleryImage renders a plain <img> (see alt).

classNamestring

Additional className for the image

src(required)string

Current image source URL; changing it triggers the crossfade transition.

ImageSkeleton

PropTypeDefaultDescription
classNamestring

LoadingImage

PropTypeDefaultDescription
children(required)(props: LoadingImageRenderProps) => ReactNode

Render the image (e.g. next/image, native img), applying the given props.

classNamestring

Additional className handed to the image.