# React Native Image

> A React Native image for iOS, Android and the web: a frame that holds its size while the picture loads, a placeholder, a fade in, a fallback when it fails, and alt text for screen readers.

# 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](./avatar) for people.

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

```tsx live
import { Image, Text, VStack } from 'patine-ui';

export default function Example() {
  return (
    <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>
  );
}
```

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

```tsx live
import { Pressable } from 'react-native';
import { HStack, Image, Text, VStack } from 'patine-ui';

const STORIES = [
  { id: 1, src: 'https://picsum.photos/id/1067/800/450', section: 'Cities', title: 'The town that gave its streets back to bikes', time: '6 min read' },
  { id: 2, src: 'https://invalid.example/missing.jpg', section: 'Science', title: 'What a year without snow did to the glaciers', time: '9 min read' },
  { id: 3, src: 'https://picsum.photos/id/292/800/450', section: 'Food', title: 'Ten recipes that start with a tin of beans', time: '4 min read' },
];

export default function Example() {
  return (
    <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).

```tsx live
import { HStack, Image } from 'patine-ui';

const SRC = 'https://picsum.photos/id/1025/640/480';

export default function Example() {
  return (
    <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.

```tsx live
import { HStack, Image } from 'patine-ui';

const SRC = 'https://picsum.photos/id/1015/320/320';

export default function Example() {
  return (
    <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.

```tsx live
import { HStack, Image, Text } from 'patine-ui';

export default function Example() {
  return (
    <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](../guides/designs), or `'native'` for the platform's own. |

## Related

- [Avatar](./avatar): a person's picture with an initials fallback.
- [ImageViewer](./image-viewer): opens pictures full screen.
- [Skeleton](./skeleton): placeholders for the rest of a loading screen.
