react-native-nitro-image

Nitro Image is a superfast Image core type and view component for React Native, built with Nitro!

- Powered by Nitro Modules for highly efficient native bindings! 🔥
- Instance-based Image type with byte-buffer pixel data access 🔗
- Supports in-memory image operations like resizing and cropping without saving to file 📐
- Supports deferred ImageLoader types to optimize for displaying large lists of Images ⏳
- Fast Web Image loading and caching using SDWebImage (iOS) and Coil (Android) 🌎
- ThumbHash support for elegant placeholders 🖼️

``tsx
function App() {
return (
image={{ filePath: '/tmp/image.jpg' }}
style={{ width: 400, height: 400 }}
/>
)
}
`

Installation

Install react-native-nitro-image from npm:

`sh
npm i react-native-nitro-image
npm i react-native-nitro-modules
cd ios && pod install
`

> [!NOTE]
> Since NitroImage is built with Nitro Views, it requires the new architecture to be enabled.

$3

To keep NitroImage super lightweight, it does not ship a web image loader and caching system.
If you want to load images from the web, install react-native-nitro-web-image as well:

`sh
npm i react-native-nitro-web-image
cd ios && pod install
`

Then, since SDWebImage does not enable modular headers for static linkage, you need to enable those yourself in your app's Podfile:

`rb
target '…' do
config = use_native_modules!

# Add this line:
pod 'SDWebImage', :modular_headers => true
`

Usage

$3

The simplest way to load an Image is to use the exported loadImage(…) method:

`ts
const webImage = await loadImage({ url: 'https://picsum.photos/seed/123/400' })
const fileImage = await loadImage({ filePath: 'file://my-image.jpg' })
const resourceImage = await loadImage({ resource: 'my-image.jpg' })
const symbolImage = await loadImage({ symbol: 'star' })
const requireImage = await loadImage(require('./my-image.jpg'))
`

Under the hood, this uses the native methods from Images or WebImages:

`ts
const webImage = await WebImages.loadFromURLAsync('https://picsum.photos/seed/123/400')
const fileImage = await Images.loadFromFileAsync('file://my-image.jpg')
const resourceImage = Images.loadFromResources('my-resource.jpg')
const symbolImage = Images.loadFromSymbol('star')
`

#### Creating a blank Image

Additionally, you can also create a new blank Image:

`ts
const blank = Images.createBlankImage(100, 100, /enableAlpha:/ true)
`

If you want to fill the blank image with a specific background color, pass the color in RGB:

`ts
const blankRedImage = Images.createBlankImage(100,
100,
/enableAlpha:/ true,
{ r: 1, g: 0, b: 0 })
`

#### Load with Options

When loading from a remote URL, you can tweak options such as priority:

`ts
const image1 = await WebImages.loadFromURLAsync(URL1, { priority: 'low' })
const image2 = await WebImages.loadFromURLAsync(URL2, { priority: 'high' })
`

#### Preloading

If you know what Images are going to be rendered soon, you can pre-load them using the preload(...) API:

`ts
WebImages.preload(profilePictureLargeUrl)
`

#### require(…)

A React Native require(…) returns a resource-ID. In debug, resources are streamed over Metro (localhost://…), while in release, they are embedded in the resources bundle.
NitroImage wraps those APIs so you can just pass a require(…) to useImage(…), useImageLoader(…), or directly:

`ts
const image = useImage(require('./image.png'))
`

#### RawPixelData (ArrayBuffer)

The Image type can be converted to- and from- an ArrayBuffer, which gives you access to the raw pixel data in an RGB format:

`ts
const image = ...
const pixelData = await image.toRawPixelData()
const sameImageCopied = await Images.loadFromRawPixelData(pixelData)
`

#### EncodedImageData (ArrayBuffer)

The Image type can be encoded to- and decoded from- an ArrayBuffer using a container format like jpg, png or heic:

`ts
const image = ...
const imageData = await image.toEncodedImageData('jpg', 90)
const sameImageCopied = await Images.loadFromEncodedImageData(imageData)
`

#### Resizing

An Image can be resized entirely in-memory, without ever writing to- or reading from- a file:

`ts
const webImage = await WebImages.loadFromURLAsync('https://picsum.photos/seed/123/400')
const smaller = await webImage.resizeAsync(200, 200)
`

#### Cropping

An Image can be cropped entirely in-memory, without ever writing to- or reading from- a file:

`ts
const webImage = await WebImages.loadFromURLAsync('https://picsum.photos/seed/123/400')
const smaller = await webImage.cropAsync(100, 100, 50, 50)
`

#### Rotating

An Image can be rotated entirely in-memory, without ever writing to- or reading from- a file:

`ts
const webImage = await WebImages.loadFromURLAsync('https://picsum.photos/seed/123/400')
const upsideDown = await webImage.rotateAsync(180)
`

#### Render into another Image

An Image can be rendered into another Image entirely in-memory. This creates a third image (the result):

`ts
const image1 = ...
const image2 = ...
const result = await image1.renderIntoAsync(image2, 10, 10, 80, 80)
`

#### Saving

An in-memory Image object can also be written/saved to a file:

`ts
const image = ...
const path = await image.saveToTemporaryFileAsync('jpg', 90)
`

#### Compressing

Images can be compressed using the jpg container format - either in-memory or when writing to a file:

`ts
const image = ...
const path = await image.saveToTemporaryFileAsync('jpg', 50) // 50% compression
const compressed = await image.toEncodedImageData('jpg', 50) // 50% compression
`

#### HEIC/HEIF

NitroImage supports HEIC/HEIF format if the host OS natively supports it.

| | iOS | Android |
|--------------|----------------|----------------|
| Loading HEIC | ✅ | ✅ (>= SDK 28) |
| Writing HEIC | ✅ (>= iOS 17) | ❌ |

You can check whether your OS supports HEIC via NitroImage:

`ts
import { supportsHeicWriting } from 'react-native-nitro-modules'

const image = ...
const format = supportsHeicWriting ? 'heic' : 'jpg'
const path = await image.saveToTemporaryFileAsync(format, 100)
`

$3

#### The useImage() hook

The useImage() hook asynchronously loads an Image from the given source and returns it as a React state:

`tsx
function App() {
const image = useImage({ filePath: '/tmp/image.jpg' })
return …
}
`

#### The useImageLoader() hook

The useImageLoader() hook creates an asynchronous ImageLoader which can be passed to a view to defer image loading:

`tsx
function App() {
const loader = useImageLoader({ filePath: '/tmp/image.jpg' })
return (
image={loader}
style={{ width: 400, height: 400 }}
/>
)
}
`

$3

The view is a React Native view that allows you to render Image - either asynchronously (by wrapping ImageLoaders), or synchronously (by passing Image instances directly):

`tsx
function App() {
return (
image={{ filePath: '/tmp/image.jpg' }}
style={{ width: 400, height: 400 }}
/>
)
}
`

$3

The view is the actual native Nitro View component for rendering an Image instance. It is recommended to use abstractions like instead of the actual native component. However if you need to use the native component instead, it is still exposed:

`tsx
function App() {
const image = …
return (
image={image}
style={{ width: 400, height: 400 }}
/>
)
}
`

#### Dynamic width or height

To achieve a dynamic width or height calculation, you can use the image's dimensions:

`tsx
function App() {
const { image, error } = useImage({ filePath: '/tmp/image.jpg' })
const aspect = (image?.width ?? 1) / (image?.height ?? 1)
return (
image={image}
style={{ width: '100%', aspectRatio: aspect }}
/>
)
}
`

This will now resize the height dimension to match the same aspect ratio as the image - in this case it will be 1:1 since the image is 400x400.

If the image is 400x200, the height of the view will be half of the width of the view, i.e. a 0.5 aspect ratio.

$3

A ThumbHash is a short binary (or base64 string) representation of a blurry image.
Since it is a very small buffer (or base64 string), it can be added to a payload (like a user object in your database) to immediately display an image placeholder while the actual image loads.

#### ThumbHash (ArrayBuffer) <> Image

NitroImage supports conversion from- and to- ThumbHash representations out of the box.

For performance reasons, a ThumbHash is represented as an ArrayBuffer.

`ts
const thumbHash = ...from server
const image = Images.loadFromThumbHash(thumbHash)
const thumbHashAgain = image.toThumbHash()
`

##### ThumbHash (ArrayBuffer) <> Base64 String

If your ThumbHash is a string, convert it to an ArrayBuffer first, since this is more efficient:

`ts
const thumbHashBase64 = ...from server
const thumbHashArrayBuffer = thumbHashFromBase64String(thumbHashBase64)
const thumbHashBase64Again = thumbHashToBase64String(thumbHashArrayBuffer)
`

##### Async ThumbHash

Since ThumbHash decoding or encoding can be a slow process, you should consider using the async methods instead:

`ts
const thumbHash = ...from server
const image = await Images.loadFromThumbHashAsync(thumbHash)
const thumbHashAgain = await image.toThumbHash()
`

Using the native Image type in a third-party library

To use the native Image type in your library (e.g. in a Camera library), you need to follow these steps:

1. Add the dependency on react-native-nitro-image
- JS: Add react-native-nitro-image to peerDependencies and devDependencies
- Android: Add :react-native-nitro-image to your build.gradle's dependencies, and react-native-nitro-image::NitroImage to your CMake's dependencies (it's a prefab)
- iOS: Add NitroImage to your *.podspec's dependencies
2. In your Nitro specs (*.nitro.ts), just import Image from 'react-native-nitro-image' and use it as a type
3. In your native implementation, you can either;
- Implement HybridImageSpec, HybridImageLoaderSpec or HybridImageViewSpec with your custom implementation, e.g. to create a Image implementation that doesn't use UIImage but instead uses CGImage, or an AVPhoto
- Use the HybridImageSpec, HybridImageLoaderSpec or HybridImageViewSpec types. You can either use them abstract (with all the methods that are also exposed to JS), or by downcasting them to a specific type - all of them follow a protocol like NativeImage:
`swift
class HybridCustom: HybridCustomSpec {
func doSomething(image: any HybridImageSpec) throws {
guard let image = image as? NativeImage else { return }
let uiImage = image.uiImage
// ...
}
}
`
4. Done! 🎉 Now you can benefit from a common, shared Image type - e.g. your Camera library can directly return an Image instance in takePhoto(), which can be instantly rendered using ` - no more file I/O!