Image

A lightweight cross-platform Image with Tamagui style props

Image provides a lightweight cross-platform image component with Tamagui style props and pluggable renderers.

Features

Server rendering support
Native and web support
Full Tamagui style props
Pluggable image renderers, including expo-image, through createImage

Installation

Image is already installed in tamagui, or you can install it independently:

yarnnpmbunpnpm
yarn add @tamagui/image

Usage

Use the src prop for the image URL:

import { Image } from 'tamagui'

export default () => (
  <Image src="https://example.com/photo.jpg" width={200} height={200} />
)

Use objectFit to control how the image fits its container:

<Image src="https://example.com/photo.jpg" width="100%" height={300} objectFit="cover" />

Sizing on native

width and height are Tamagui layout props. On native, they become React Native Image styles. Remote images must resolve to a nonzero layout size, so use fixed dimensions or place percentage-sized images inside a parent with defined dimensions:

<html.div width={320} height={200}>
  <Image
    src="https://example.com/photo.jpg"
    width="100%"
    height="100%"
    objectFit="cover"
  />
</html.div>

Tamagui converts a string src to source={{ uri: src }} on native. Layout dimensions stay in style; they are not copied into the native source metadata. React Native source objects remain supported for migration, but src is preferred.

Using with expo-image

For better performance and features like blurhash placeholders and transitions, you can use createImage to create a custom Image component with expo-image:

import { Image as ExpoImage } from 'expo-image'
import { createImage } from '@tamagui/image'

export const Image = createImage({
  Component: ExpoImage,
  resizeModePropName: 'contentFit',
  objectPositionPropName: 'contentPosition',
})

Now you can use all expo-image props alongside Tamagui’s unified API:

const blurhash = '|rF?hV%2WCj[ayj[a|j[az...'

export default () => (
  <Image
    src="https://example.com/photo.jpg"
    width={200}
    height={300}
    objectFit="cover"
    placeholder={{ blurhash }}
    transition={300}
  />
)

createImage options

Option

Type

Default

Description

Component

ComponentType

The underlying image component (expo-image, react-native-fast-image, etc.)

resizeModePropName

string

'resizeMode'

The prop name for resize mode. expo-image uses 'contentFit'

objectPositionPropName

string

undefined

The prop name for object position. expo-image uses 'contentPosition'

mapObjectFitToResizeMode

function

Default mapper

Custom function to map objectFit values to the component's resize mode

transformSource

function

Default transformer

Custom function to transform source props

Accessibility

Always provide an alt attribute describing the image content. For decorative images, use an empty string (alt="").

// meaningful image
<Image
  src="/team-photo.jpg"
  alt="The Tamagui team at React Conf 2024"
  width={400}
  height={300}
/>

// decorative image
<Image
  src="/decorative-bg.jpg"
  alt=""
  width={400}
  height={300}
/>

On React Native, use accessible and accessibilityLabel for screen reader support. See the React Native Accessibility docs for details.

<Image
  src="/avatar.jpg"
  accessible
  accessibilityLabel="User profile photo"
  width={64}
  height={64}
/>

API reference

Image

Extends View with Tamagui props, plus:

Props

src

string | number

The image URL or native require() result. Preferred over `source` for better web alignment.

alt

string

Alternative text describing the image for accessibility. Use empty string for decorative images.

objectFit

'cover' | 'contain' | 'fill' | 'none' | 'scale-down'

How the image should be resized to fit its container. Maps to CSS object-fit on web and resizeMode on native.

objectPosition

string

How the image should be positioned within its container. On native, requires expo-image or similar for full support.

source

ImageSourcePropType

Deprecated React Native source prop. It remains supported during migration; prefer `src`.

resizeMode

ImageResizeMode

Deprecated. Use `objectFit` instead.

Web-only props

These props pass through to the native <img> element on web:

Props

loading

'lazy' | 'eager'

Lazy load images below the fold. Use eager (default) for above-the-fold images.

decoding

'async' | 'sync' | 'auto'

Hint for how the browser should decode the image. Use async for non-blocking decode.

fetchPriority

'high' | 'low' | 'auto'

Hint for fetch priority. Use high for LCP (largest contentful paint) images.

srcSet

string

Comma-separated list of image sources with width descriptors for responsive images.

sizes

string

Media conditions describing the image display size, used with srcSet.

crossOrigin

'anonymous' | 'use-credentials'

CORS setting for the image request.

referrerPolicy

string

Referrer policy for the image request.

Accessibility props

Props

alt

string

Alternative text for screen readers. Required for meaningful images, use empty string for decorative.

accessible

boolean

Native only. Marks the image as an accessible element.

accessibilityLabel

string

Native only. Label read by screen readers. Use with accessible={true}.

aria-label

string

Overrides alt as the accessible name. Prefer using alt instead.

aria-describedby

string

References an element providing extended description.

aria-hidden

boolean

Hides the image from assistive technology. Alternative to alt="".

role

string

Set to 'presentation' or 'none' for decorative images, or 'img' (default).

Web props like loading, srcSet, and fetchPriority only apply on web. On native, use expo-image via createImage for advanced features like blurhash placeholders and priority loading.

Card

ListItem

Edit this page on GitHub.