Image

Supports SSR.
Works on native and web.
Accepts Hanzo GUI style props.
Pluggable architecture with createImage for expo-image and more.

Installation

Image is already installed in @hanzo/gui, or you can install it independently:

npm install @hanzogui/image

Usage

Use the src prop for the image URL:

import { Image } from '@hanzo/gui'

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

You can also use objectFit to control how the image fits its container:

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

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 '@hanzogui/image'

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

Now you can use all expo-image props alongside Hanzo GUI'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

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 Hanzo GUI 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

Extends View with Gui props, plus:

Prop	Type	Default	Required
src	string	-	-
alt	string	-	-
objectFit	'cover' \| 'contain' \| 'fill' \| 'none' \| 'scale-down'	-	-
objectPosition	string	-	-
source	ImageSourcePropType	-	-
resizeMode	ImageResizeMode	-	-

Web-only Props

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

Prop	Type	Default	Required
loading	'lazy' \| 'eager'	-	-
decoding	'async' \| 'sync' \| 'auto'	-	-
fetchPriority	'high' \| 'low' \| 'auto'	-	-
srcSet	string	-	-
sizes	string	-	-
crossOrigin	'anonymous' \| 'use-credentials'	-	-
referrerPolicy	string	-	-

Accessibility Props

Prop	Type	Default	Required
alt	string	-	-
accessible	boolean	-	-
accessibilityLabel	string	-	-
aria-label	string	-	-
aria-describedby	string	-	-
aria-hidden	boolean	-	-
role	string	-	-

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.

Image

On this page