Skip to main content

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'.

Loading…
<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​

Props
src
aspectRatio
fit
radius
design
<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.

Loading…
<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).

Loading…
<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.

Loading…
<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.

Loading…
<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​

PropTypeDefaultDescription
srcstring | ImageSourcePropType—The picture: a URL or an image source.
altstring—What it shows, read by screen readers. Without it the image is decorative.
widthDimensionValue'100%'The frame's width.
heightDimensionValue—The frame's height.
aspectRationumber—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.
radiuskeyof Theme['radius'] | numberthe design'sA radius step, 'full' for a circle, or points.
placeholderReactNodea breathing placeholderShown while loading.
fallbackReactNodea picture glyphShown 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.
styleStyleProp<ViewStyle>—The frame.
themeDeepPartial<Theme>—Theme override.
design'brand' | 'ios' | 'material' | 'web' | 'native'from PatineProviderThe look to follow: brand, iOS, Material or web, or 'native' for the platform's own.
  • Avatar: a person's picture with an initials fallback.
  • ImageViewer: opens pictures full screen.
  • Skeleton: placeholders for the rest of a loading screen.