Image
Images with aspect ratios, captions, error fallbacks, and a built-in lightbox.
"use client";
import { Image, Box } from "astralis-ui";
export function ImageDemo() {
return (
<Box w="full" maxW="xs">
<Image
src="/placeholder.svg"
alt="A starfield gradient"
aspectRatio="video"
rounded="xl"
caption="Captions wrap the image in a semantic figure."
/>
</Box>
);
}Import#
import { Image } from "astralis-ui";
// Image.Group for galleriesPreview lightbox#
preview makes the image click-to-zoom — the lightbox supports zoom, rotate
and keyboard dismissal, with arrow-key navigation inside an Image.Group.
Click the image to preview
"use client";
import { Image, Text, VStack, Box } from "astralis-ui";
export function ImagePreview() {
return (
<VStack gap="2">
<Box w="56">
{/* Click to open the built-in lightbox (zoom, rotate, Esc to close). */}
<Image src="/placeholder.svg" alt="Preview me" aspectRatio="video" rounded="lg" preview />
</Box>
<Text size="xs" color="muted">Click the image to preview</Text>
</VStack>
);
}Error fallbacks#
"use client";
import { Image, HStack } from "astralis-ui";
export function ImageFallback() {
return (
<HStack gap="4" wrap="wrap" justifyContent="center">
{/* A broken src falls back to the default icon… */}
<Image src="/does-not-exist.png" alt="Broken" width={140} height={90} rounded="lg" />
{/* …or to whatever you pass as fallback. */}
<Image
src="/also-missing.png"
alt="Broken with custom fallback"
width={140}
height={90}
rounded="lg"
fallback={<span>No image 😢</span>}
/>
</HStack>
);
}Props#
| Prop | Type | Default | Description |
|---|---|---|---|
src / alt | string | required | Source and alt text. |
aspectRatio | "square" | "video" | "portrait" | "wide" or CSS ratio | — | Locks the frame. |
objectFit | "cover" | "contain" | "fill" | "none" | "scale-down" | "cover" | Fit inside the frame. |
rounded | "none" – "3xl" | "full" | "none" | Corner radius. |
loading | "lazy" | "eager" | "lazy" | Native lazy loading. |
placeholder | "blur" | "empty" or URL | "empty" | Shimmer or blurred stand-in while loading. |
fallback | ReactNode | icon | Rendered on load error. |
caption | ReactNode | — | Wraps in figure + figcaption. |
preview | boolean | false | Click-to-zoom lightbox. |
Image.Group#
| Prop | Type | Default | Description |
|---|---|---|---|
items | { src, alt, caption? }[] | required | The gallery images. |
columns | 2 | 3 | 4 | 3 | Grid columns. |
gap | "sm" | "md" | "lg" | "md" | Grid gap. |
Keyboard#
With the preview lightbox open:
| Key | Action |
|---|---|
Esc | Close the lightbox |
← / → | Previous / next image (inside an Image.Group) |