Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

expo-image

expo2.6mMIT2.3.2TypeScript support: included

A cross-platform, performant image component for React Native and Expo with Web support

react-native

readme

Expo logo

Expo

Expo SDK version Chat or ask a question License: MIT Downloads

Try Expo in the Browser  •  Read the Documentation  •  Learn more on our blog  •  Request a feature

Follow us on

Expo on X   Expo on GitHub   Expo on Reddit   Expo on Bluesky   Expo on LinkedIn

Introduction

Expo is an open-source platform for making universal native apps that run on Android, iOS, and the web. It includes a universal runtime and libraries that let you build native apps by writing React and JavaScript.

This repository includes the Expo SDK, Modules API, Go app, CLI, Router, documentation, and various other supporting tools. Expo Application Services (EAS) is a platform of hosted services that are deeply integrated with Expo open source tools. EAS helps you build, ship, and iterate on your app as an individual or a team.

Read the Expo Community Guidelines before interacting in the repository. Thank you for helping keep the Expo community open and welcoming!

Table of contents

📚 Documentation

Learn about building and deploying universal apps in our official docs!

🗺 Project Layout

  • packages All the source code for Expo modules, if you want to edit a library or just see how it works this is where you'll find it.
  • apps This is where you can find Expo projects which are linked to the development modules. You'll do most of your testing in here.
  • apps/expo-go This is where you can find the source code for Expo Go.
  • apps/expo-go/ios/Exponent.xcworkspace is the Xcode workspace. When developing iOS, always open this instead of Exponent.xcodeproj because the workspace also loads the CocoaPods dependencies.
  • docs The source code for https://docs.expo.dev
  • templates The template projects you get when you run npx create-expo-app
  • react-native-lab This is our fork of react-native used to build Expo Go.
  • guides In-depth tutorials for advanced topics like contributing to the client.
  • tools contain build and configuration tools.
  • template-files contains templates for files that require private keys. They are populated using the keys in template-files/keys.json.
  • template-files/ios/dependencies.json specifies the CocoaPods dependencies of the app.

🏅 Badges

Let everyone know your app can be run instantly in the Expo Go app!

runs with Expo Go

runs with Expo Go

[![runs with Expo Go](https://img.shields.io/badge/Runs%20with%20Expo%20Go-000.svg?style=flat-square&logo=EXPO&labelColor=f3f3f3&logoColor=000)](https://expo.dev/client)

[![runs with Expo Go](https://img.shields.io/badge/Runs%20with%20Expo%20Go-4630EB.svg?style=flat-square&logo=EXPO&labelColor=f3f3f3&logoColor=000)](https://expo.dev/client)

👏 Contributing

If you like Expo and want to help make it better then check out our contributing guide! Check out the CLI package to work on the Expo CLI.

❓ FAQ

If you have questions about Expo and want answers, then check out our Frequently Asked Questions!

If you still have questions you can ask them on our Discord and Forums or X @expo.

💙 The Team

Curious about who makes Expo? Here are our team members!

License

The Expo source code is made available under the MIT license. Some of the dependencies are licensed differently, with the BSD license, for example.

Star the Expo repo on GitHub to support the project

changelog

Changelog

Unpublished

🛠 Breaking changes

🎉 New features

🐛 Bug fixes

💡 Others

2.3.2 — 2025-07-01

🐛 Bug fixes

  • [iOS] Use specified cache type when no transformation is applied (#37777 by @jakex7)

2.3.1 — 2025-07-01

🐛 Bug fixes

  • [iOS] Fixed contentPosition is not correct after switching theme. (#37374 by @kudo)

📚 3rd party library updates

  • [Android] Bumped GIF Glide plugin to 3.0.5 for Android 16KB page size support. (#37454 by @kudo)

2.3.0 — 2025-06-11

🛠 Breaking changes

  • [iOS] useAppleWebpCodec has been moved from the source object to the component's prop to make it usable with the local assets. (#37300 by @tsapeta)

2.2.1 — 2025-06-10

This version does not introduce any user-facing changes.

2.2.0 — 2025-06-04

🎉 New features

  • Add imperative api to lock/unlock/reload resource. (#36912 by @jakex7)

🐛 Bug fixes

  • Fix React Server Components support. (#36801 by @EvanBacon)
  • [iOS] Fix PhotoLibrary assets being scaled twice. (#36776 by @alanjhughes)
  • [iOS] Don't add transformers when unnecessary. (#36884 by @jakex7)
  • [iOS] Fix blurry images when using tintColor by scaling imageThumbnailPixelSize with screen density. (#37235 by @hirbod)

2.1.7 — 2025-05-06

This version does not introduce any user-facing changes.

2.1.6 — 2025-04-30

This version does not introduce any user-facing changes.

2.1.5 — 2025-04-25

🐛 Bug fixes

  • Fixed CUICatalog: Invalid asset name supplied: '' error on iOS when the path is empty. (#36294 by @Innei)

2.1.4 — 2025-04-14

🐛 Bug fixes

  • Fixed SVG image tinting on iOS. (#35927 by @kudo)
  • [Android] Fixed OutOfMemoryError crash when displaying some gif images (#36097 by @rahimrahman)

2.1.3 — 2025-04-11

This version does not introduce any user-facing changes.

2.1.2 — 2025-04-09

This version does not introduce any user-facing changes.

2.1.1 — 2025-04-08

🐛 Bug fixes

2.1.0 — 2025-04-04

🛠 Breaking changes

🎉 New features

  • type-compatibility with react-native 0.77 (#34027 by @vonovak)
  • Added ImageSource.useAppleWebpCodec on iOS to allow using libwebp codec for better animation performance on some images. (#35802 by @kudo)

🐛 Bug fixes

💡 Others

📚 3rd party library updates

2.0.7 - 2025-03-26

🐛 Bug fixes

  • [iOS] Fixed image be cropped with contentPosition on New Architecture mode. (#35630 by @kudo)

2.0.6 - 2025-02-19

🐛 Bug fixes

2.0.5 - 2025-02-10

🐛 Bug fixes

2.0.4 - 2025-01-10

This version does not introduce any user-facing changes.

2.0.3 - 2024-11-29

🐛 Bug fixes

  • [Android] Fixed useImage causing a native crash when uri is unresolvable. (#33268 by @lukmccall)
  • [Android] Fixes adding a blurhash placeholder to Image or ImageBackground causing blurry version of the image. (#33272 by @lukmccall)

2.0.2 — 2024-11-22

💡 Others

2.0.1 — 2024-11-19

🐛 Bug fixes

  • [Android] Fixes Gif animations never stopping even when loop count is set to 1. (#32944 by @lukmccall)
  • [Android] Fixed borderColor is not applied. (#33026 by @lukmccall)
  • [Android] Fixed border related props weren't applied correctly. (#33078 by @lukmccall)

💡 Others

  • [Android] migrate ImageView to CSSBackgroundDrawable (#33024 by @vonovak)

2.0.0 — 2024-11-11

This version does not introduce any user-facing changes.

2.0.0-preview.1 — 2024-10-31

🐛 Bug fixes

  • Fixed displaying a placeholder when useImage hook is used. (#32430 by @tsapeta)

2.0.0-preview.0 — 2024-10-22

🛠 Breaking changes

🎉 New features

🐛 Bug fixes

  • Fix props not being passed to parent container. (#29416 by @aleqsio)
  • Add missing react and react-native peer dependencies for isolated modules. (#30469 by @byCedric)
  • Add missing react-native-web optional peer dependency for isolated modules. (#30689 by @byCedric)
  • [Web] Fix type incompatibility between style prop and @types/react-native-web (#31150 by @adamhari)
  • [iOS] Fixed isAnimated property always returning true. (#31834 by @tsapeta)
  • [iOS] Fixed stopAnimating broken on downscaled animated images. (#32053 by @kudo)

💡 Others

⚠️ Notices

1.13.0 - 2024-09-23

🎉 New features

1.12.15 - 2024-08-24

This version does not introduce any user-facing changes.

1.12.13 - 2024-07-16

🐛 Bug fixes

1.12.12 - 2024-06-13

💡 Others

  • Removed @react-native/assets-registry dependency. (#29541 by @kudo)

1.12.11 - 2024-06-06

This version does not introduce any user-facing changes.

1.12.10 - 2024-06-05

💡 Others

  • Pin @react-native subpackage versions to 0.74.83. (#29441 by @kudo)

1.12.9 — 2024-05-09

💡 Others

1.12.8 — 2024-05-06

This version does not introduce any user-facing changes.

1.12.7 — 2024-05-04

🎉 New features

  • Added support for displaying animated AVIF images on Android. (#28609 by @fobos531)

🐛 Bug fixes

1.12.6 — 2024-05-02

This version does not introduce any user-facing changes.

1.12.5 — 2024-05-01

This version does not introduce any user-facing changes.

1.12.4 — 2024-04-24

🐛 Bug fixes

  • Fixed an issue where certain images would not animate at certain sizes on iOS. (#28335 by @fobos531)
  • Fixed SVG assets without viewbox attribute not being rendered on Android. (#28369 by @lukmccall)

1.12.3 — 2024-04-23

This version does not introduce any user-facing changes.

1.12.2 — 2024-04-22

🐛 Bug fixes

1.12.1 — 2024-04-19

This version does not introduce any user-facing changes.

1.12.0 — 2024-04-18

🎉 New features

  • On iOS, support loading assets in the native project. This already worked on android. (#27251 by @alanjhughes)
  • Support prefetching images with HTTP headers. (#28133 by @toy0605)

🐛 Bug fixes

  • [iOS] Fixed an issue where data URIs caused crashes on iOS16+. (#28320 by @aleqsio)
  • Refactor web implementations of useSourceSelection to avoid unnecessary rerenders. (#27569 by @aleqsio)
  • Fixed an issue where isBlurhashString always returned true .(#27251 by @alanjhughes)
  • Fix #available check to account for tvOS. (#27272 by @alanjhughes)
  • Fixed jest may cause RangeError: Invalid string length error when generating a snapshot. (#27354 by @lukmccall)
  • Fixed placeholders weren't correctly scaled down on the Android. (#28255 by @lukmccall)

💡 Others

  • [iOS] Bump SDWebImage to 5.19.1 to include the 3rd-party privacy manifest. (#27874 by @aparedes, by @tsapeta)
  • Use typeof window checks for removing server code. (#27514 by @EvanBacon)
  • Removed deprecated backward compatible Gradle settings. (#28083 by @kudo)
  • [iOS] Bump SDWebImageWebPCoder to 0.14.6. (#28273 by @alanjhughes)
  • Automatically clean blurhash cache when the app's memory is running low. (#28276 by @lukmccall)

1.11.0 — 2024-02-05

🎉 New features

  • [Android] Adds new prop decodeFormat to specify the format that should be used during the decoding process. (#26442 by @lukmccall)
  • [iOS] Added generateBlurhashAsync function. (#26430 by @aleqsio)
  • [Android] Adds automatic downsampling when the asset exceeds the hardware bitmap size limit. (#26792 by @lukmccall)

🐛 Bug fixes

1.10.4 - 2024-01-18

This version does not introduce any user-facing changes.

1.10.3 - 2024-01-12

This version does not introduce any user-facing changes.

1.10.2 - 2024-01-10

🐛 Bug fixes

  • [Android] Fixed the issue with the application of tint color when an element does not have a style assigned to it. (#26251 by @lukmccall)
  • [Android] Fixed the tint color wasn't applied to the root element. (#26339 by @lukmccall)
  • [Android] Fixed that the tint color on SVGs can't be changed dynamically. (#26350 by @lukmccall)

💡 Others

  • Replace deprecated com.facebook.react:react-native:+ Android dependency with com.facebook.react:react-android. (#26237 by @kudo)

1.10.1 - 2023-12-19

This version does not introduce any user-facing changes.

1.10.0 — 2023-12-12

🎉 New features

1.9.0 — 2023-11-14

🛠 Breaking changes

🎉 New features

  • [Android] The stability of the memory cache key generation has been improved. (#25372 by @lukmccall)

💡 Others

  • Collapse re-export of react-native/Libraries/Image/AssetRegistry to @react-native/assets-registry/registry. (#25265 by @EvanBacon)
  • [Android] Changed how the tintColor is applied to the SVG. (#25377 by @lukmccall)

1.8.0 — 2023-11-13

🎉 New features

  • Return a promise in the prefetch method. (#25196 by @gkasdorf)
  • [Android] Added autoplay prop and startAnimating() and stopAnimating() functions to reflect changes made to iOS in #25008. (#25124 by @gkasdorf)

🐛 Bug fixes

  • [Android] Fix contentFit not working for SVG images. (#25187 by @behenate)
  • [iOS] Start loading the image before the view mounts to fix issues with the PagerView. (#25343 by @tsapeta)
  • [Android] Fix SVG not scaling correctly in the release mode. (#25326 by @lukmccall)
  • [Android] Fix incorrect intrinsicSize returned for SVGs. (#25048 by @behenate)

💡 Others

1.7.0 — 2023-11-01

🎉 New features

  • [iOS] Added support for allowDownscaling prop. (#25012 by @behenate)
  • Added getCachePathAsync() to retrieve the path of the cached image file if it exists (#24980 by @gkasdorf)
  • [iOS] Added autoplay prop to control whether an animated image will automatically animate or not (#25008 by @gkasdorf)
  • [iOS] Added startAnimating() and stopAnimating() functions to start or stop an image's animation (#25008 by @gkasdorf)

🐛 Bug fixes

  • [Android] fix crash when loading local image files with no file extension (#24201 by @kadikraman)
  • [iOS] Fix compilation on tvOS. (#25010 by @douglowder)
  • [iOS] Fixed issue where some animated images would cause the app to hang (#25008 by @gkasdorf)

1.6.1 — 2023-11-01

🐛 Bug fixes

  • [Android] fix crash when loading local image files with no file extension (#24201 by @kadikraman)

1.3.5 — 2023-11-01

🐛 Bug fixes

  • [Android] fix crash when loading local image files with no file extension (#24201 by @kadikraman)

1.6.0 — 2023-10-17

🛠 Breaking changes

🎉 New features

🐛 Bug fixes

  • Remove GlideWebpDecoder until they update their libwebp dependency. (#24656 by @alanjhughes)
  • [web] Fix content fit not being applied correctly when using hash placeholders. (#24542 by @aleqsio)
  • [macCatalyst] Fix build with ImageAnalyzer on macCatalyst below 17.0. (#24880 by @kesha-antonov)

💡 Others

  • Ship untranspiled JSX to support custom handling of jsx and createElement. (#24889 by @EvanBacon)
  • Make placeholderContentFit visible in the docs. (#24801 by @behenate)

1.0.2 — 2023-09-29

🐛 Bug fixes

  • Remove GlideWebpDecoder until they update their libwebp dependency. (#24656 by @alanjhughes)

1.3.4 — 2023-09-28

🐛 Bug fixes

  • Remove GlideWebpDecoder until they update their libwebp dependency. (#24656 by @alanjhughes)

1.5.2 — 2023-09-18

This version does not introduce any user-facing changes.

1.3.3 — 2023-09-15

🐛 Bug fixes

  • Fixed placeholders aren't always replaced by full-size images on Android. (#23705 by @lukmccall)
  • Fix the image components rendering incorrect assets when the Proguard is enabled on Android. (#23704 by @lukmccall)
  • Fixed gif and awebp memory leak on Android. (#24259 by @jingpeng)
  • Suppress "Operation cancelled by user during sending the request" error when the load request is canceled (interrupted) by a new one. (#24279 by @tsapeta)

1.5.1 — 2023-09-11

🐛 Bug fixes

  • Suppress "Operation cancelled by user during sending the request" error when the load request is canceled (interrupted) by a new one. (#24279 by @tsapeta)
  • Fixed gif and awebp memory leak on Android. (#24259 by @jingpeng)

1.5.0 — 2023-09-04

🎉 New features

  • Added support for React Native 0.73. (#24018 by @kudo)

💡 Others

1.4.1 — 2023-08-02

This version does not introduce any user-facing changes.

1.4.0 — 2023-07-28

🎉 New features

  • [Web] Add support for tintColor prop on web. (#23434 by @aleqsio)
  • [Web] Add support for static image responsiveness using srcset attributes. (#22088 by @aleqsio)

🐛 Bug fixes

  • Fixed placeholders aren't always replaced by full-size images on Android. (#23705 by @lukmccall)
  • Fixed the image components rendering incorrect assets when the Proguard is enabled on Android. (#23704 by @lukmccall)

💡 Others

  • [Web] Refactored and split some functions for better readability. (#23465 by @aleqsio)

1.3.2 - 2023-07-12

🐛 Bug fixes

  • [iOS] Fixed tintColor prop not working for SVGs. (#23418 by @tsapeta)

1.3.1 - 2023-06-29

🐛 Bug fixes

  • Fixed an issue where recyclingKey would reset the image source on mount. (#23187 by @hirbod)

1.3.0 — 2023-06-13

🎉 New features

🐛 Bug fixes

  • Fixed styles order breaking layouting on web. (#22630 by @aleqsio)
  • Uses prop spreading on web to pass all unused props to the native image component (#22340 by @makkarMeenu)
  • Fixed Android build warnings for Gradle version 8. (#22537, #22609 by @kudo)

💡 Others

  • Updated SDWebImage to 5.15.8, SDWebImageWebPCoder to 0.11.0 and SDWebImageSVGCoder to 1.7.0. (#22576 by @tsapeta)

1.2.3 — 2023-05-16

🐛 Bug fixes

  • Upgrade SDWebImageAVIFCoder to fix compiling issue with libavif < 0.11.0. (#22491 by @matinzd)

1.2.2 — 2023-04-27

🐛 Bug fixes

  • Fix for the "limited" media library permission. (#22261 by @tsapeta)

1.2.1 — 2023-04-17

🐛 Bug fixes

  • [Android] Fix url property returned by the onLoad event. (#22161 by @lukmccall)
  • [Android] Fix images not loading after the app was foregrounded. (#22159 by @lukmccall)
  • [Android] Fixed image was loaded event if the view dimensions were 0. (#22157 by @lukmccall)
  • Fix generating the image from ThumbHash that starts with a slash character. (#22160 by @tsapeta)

1.2.0 — 2023-04-14

🎉 New features

🐛 Bug fixes

  • [Web] Improve transition behavior when switching back and forth two sources. (#22099 by @aleqsio)
  • [Web] Prevent breaking in static rendering environments. (#21883 by @EvanBacon)
  • [Android] Fixed image disappearing before navigation animation is complete. (#22066 by @sallen450)
  • [Web] Fixed monorepo asset resolution in production for Metro web. (#22094 by @EvanBacon)

1.1.0 — 2023-03-25

🎉 New features

  • [Android] Add automatic asset downscaling to improve performance. (#21628 by @lukmccall)

🐛 Bug fixes

  • Fixed the tintColor not being passed to native view. (#21576 by @andrew-levy)
  • Fixed canvas: trying to use a recycled bitmap on Android. (#21658 by @lukmccall)
  • Fixed crashes caused by empty placeholder or source on Android. (#21695 by @lukmccall)
  • Fixes shouldDownscale don't respect the scale factor on iOS. (#21839 by @ouabing)
  • Fixes cache policy not being correctly applied when set to none on iOS. (#21840 by @ouabing)

1.0.0 — 2023-02-21

This version does not introduce any user-facing changes.

1.0.0-rc.2 — 2023-02-20

🎉 New features

1.0.0-rc.1 — 2023-02-14

🐛 Bug fixes

  • Fixed You can't start or clear loads in RequestListener or Target callbacks on Android. (#21192 by @lukmccall)
  • Fixed SVGs are not rendered in the release mode on Android. (#21214 by @lukmccall)
  • Stop sending onProgress event when the asset size is unknown which led to diving by zero and a crash. (#21215 by @tsapeta)

1.0.0-rc.0 — 2023-02-09

🎉 New features

  • Added placeholderContentFit prop implementation on the web. (#21106 by @aleqsio)

1.0.0-beta.6 — 2023-02-06

🎉 New features

  • Added new prop placeholderContentFit to specify custom content fit on the placeholder. (#21096 by @magrinj)

🐛 Bug fixes

  • [iOS] Fixed possible freezes by processing images concurrently off the main thread. (#21086 by @tsapeta)

1.0.0-beta.5 — 2023-02-03

This version does not introduce any user-facing changes.

1.0.0-beta.4 — 2023-01-31

🐛 Bug fixes

  • Fixed a crash on Android where isScreenReaderFocusable crashes devices below api 28. (#21012 by @alanhughes)

1.0.0-beta.3 — 2023-01-30

🐛 Bug fixes

  • Fixed a crash on iOS below 16.0 introduced by the Live Text interaction feature. (#20987 by @tsapeta)

1.0.0-beta.2 — 2023-01-25

🎉 New features

🐛 Bug fixes

1.0.0-beta.1 — 2023-01-20

🐛 Bug fixes

  • Use SDImageAWebPCoder on iOS 14+ to speed up loading WebP images. (#20897 by @tsapeta)

💡 Others

  • On Android bump compileSdkVersion and targetSdkVersion to 33. (#20721 by @lukmccall)
  • Upgraded SDWebImage to 5.15.0 and SDWebImageAVIFCoder to 0.9.4. (#20898 by @tsapeta)

1.0.0-beta.0 — 2023-01-19

🎉 New features

1.0.0-alpha.6 — 2023-01-10

🎉 New features

1.0.0-alpha.5 — 2023-01-04

🎉 New features

  • Added support for assets from the iOS Photo Library (ph:// urls). (#20700 by @tsapeta)

🐛 Bug fixes

  • Fixed ImageProps type not allowing an array of styles. (#20701 by @tsapeta)

1.0.0-alpha.4 — 2022-12-30

🐛 Bug fixes

1.0.0-alpha.3 — 2022-12-21

🎉 New features

  • Initial release 🥳