Image
A picture in a frame that keeps its size while it loads: a breathing placeholder first, a fade in when the picture arrives, and a fallback when it's missing or fails. Use it for photos in cards, feeds and product pages; use Avatar for people.
import { Image } from 'patine-ui';
It shares its name with React Native's Image. Import one of them under another name when a file needs both: import { Image as PatineImage } from 'patine-ui'.
<VStack gap="sm" style={{ maxWidth: 360 }}> <Image src="https://picsum.photos/id/1036/640/480" alt="A mountain lake at dawn" aspectRatio={4 / 3} /> <Text weight="medium">Lake Louise at dawn</Text> <Text size="sm" color="textSecondary">Banff National Park, Canada</Text> </VStack>
Try the props
srcaspectRatiofitradiusdesign<Image
alt="A mountain lake at dawn"
src={post.imageUrl}
aspectRatio={4 / 3}
/>
Example: a news feed
A reading app's feed: every story's image keeps a 16:9 frame while it loads, so the list doesn't jump, and one whose image is gone shows the section's name instead.
<VStack gap="lg" style={{ width: '100%', maxWidth: 420 }}> {STORIES.map((s) => ( <Pressable key={s.id} style={{ width: '100%' }} accessibilityRole="link" accessibilityLabel={`${s.title}, ${s.time}`}> <VStack gap="xs"> <Image src={s.src} alt="" width="100%" aspectRatio={16 / 9} radius="lg" fallback={<Text weight="semibold" color="textSecondary">{s.section}</Text>} /> <HStack gap="sm"> <Text size="xs" weight="semibold" color="primary">{s.section.toUpperCase()}</Text> <Text size="xs" color="textSecondary">{s.time}</Text> </HStack> <Text size="lg" weight="semibold">{s.title}</Text> </VStack> </Pressable> ))} </VStack>
Size and fit
width defaults to the full width of its parent. Give aspectRatio (or a height) so the frame has its size before the picture arrives and nothing below it jumps. fit is cover (fills the frame and crops, the default) or contain (shows all of it).
<HStack gap="md"> <Image src={SRC} alt="A pug in a blanket, cropped to a square" width={160} aspectRatio={1} /> <Image src={SRC} alt="A pug in a blanket" width={160} aspectRatio={1} fit="contain" /> </HStack>
Radius
radius takes a theme step (sm, md, lg…), full for a circle, or points. It defaults to the design's own.
<HStack gap="md"> <Image src={SRC} alt="A river valley" width={96} aspectRatio={1} radius={0} /> <Image src={SRC} alt="A river valley" width={96} aspectRatio={1} radius="sm" /> <Image src={SRC} alt="A river valley" width={96} aspectRatio={1} /> <Image src={SRC} alt="A river valley" width={96} aspectRatio={1} radius="full" /> </HStack>
Loading and errors
While it loads, the frame shows a placeholder that breathes (and holds still when the OS asks to reduce motion). With no src, or one that fails, it shows a picture glyph. Pass placeholder or fallback to draw your own.
<HStack gap="md"> <Image src="https://invalid.example/404.png" alt="A missing photo" width={140} aspectRatio={1} /> <Image src="https://invalid.example/404.png" alt="A missing photo" width={140} aspectRatio={1} fallback={<Text size="sm" color="textSecondary">No photo yet</Text>} /> </HStack>
Accessibility
With alt, the image is an img that screen readers name by it, and it reports itself busy while loading. Without alt it's decorative and screen readers skip it: leave alt out only when the text beside it already says what it shows.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | ImageSourcePropType | — | The picture: a URL or an image source. |
alt | string | — | What it shows, read by screen readers. Without it the image is decorative. |
width | DimensionValue | '100%' | The frame's width. |
height | DimensionValue | — | The frame's height. |
aspectRatio | number | — | Width over height, e.g. 16 / 9. Sizes the frame before the picture arrives. |
fit | 'cover' | 'contain' | 'stretch' | 'center' | 'cover' | How the picture fills the frame. |
radius | keyof Theme['radius'] | number | the design's | A radius step, 'full' for a circle, or points. |
placeholder | ReactNode | a breathing placeholder | Shown while loading. |
fallback | ReactNode | a picture glyph | Shown when there's no picture or it fails to load. |
onLoad | () => void | — | Called when the picture loads. |
onError | () => void | — | Called when it fails to load. |
style | StyleProp<ViewStyle> | — | The frame. |
theme | DeepPartial<Theme> | — | Theme override. |
design | 'brand' | 'ios' | 'material' | 'web' | 'native' | from PatineProvider | The look to follow: brand, iOS, Material or web, or 'native' for the platform's own. |
Related
- Avatar: a person's picture with an initials fallback.
- ImageViewer: opens pictures full screen.
- Skeleton: placeholders for the rest of a loading screen.