DOCSEARCHbyAlgolia
Submit Docs

react-native-nitro-image

repository·main·Indexed 20 days ago

https://github.com/mrousavy/react-native-nitro-image

A high-performance image core type and view component for React Native that utilizes Nitro Modules for efficient native bindings. It enables direct byte-buffer pixel data access and in-memory operations such as resizing, cropping, rotating, and mirroring. The library provides the <NitroImage /> component, hooks like useImage() and useImageLoader(), and support for ThumbHash placeholders. Note: Requires the React Native New Architecture to be enabled.

Tokens
8.8K
Snippets
41
Records
45
Agent score
69%

What's inside react-native-nitro-image

  1. Work with ThumbHash placeholders

    main

    NitroImage supports ThumbHash for displaying blurry image placeholders immediately. ThumbHashes are handled as ArrayBuffers for performance.

    • Sync methods: Images.loadFromThumbHash(buffer) and image.toThumbHash().
    • Async methods: Images.loadFromThumbHashAsync(buffer) and image.toThumbHashAsync() (recommended for performance as decoding/encoding can be slow).

    If your ThumbHash is a Base64 string, convert it to an ArrayBuffer first.

    // Using ArrayBuffer (Fastest)
const thumbHash      = ...from server
const image          = Images.loadFromThumbHash(thumbHash)
const thumbHashAgain = image.toThumbHash()

// Using Async (Recommended for heavy lifting)
const thumbHash      = ...from server
const image          = await Images.loadFromThumbHashAsync(thumbHash)
const thumbHashAgain = await image.toThumbHash()

  2. Integrate NitroImage into a third-party library

    main

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

    1. Add Dependencies:
      • JS: Add react-native-nitro-image to peerDependencies and devDependencies.
      • Android: Add :react-native-nitro-image to build.gradle dependencies and react-native-nitro-image::NitroImage to CMake dependencies.
      • iOS: Add NitroImage to your .podspec dependencies.
    2. Define Types: In your .nitro.ts specs, import Image from 'react-native-nitro-image'.
    3. Native Implementation: Implement HybridImageSpec, HybridImageLoaderSpec, or HybridImageViewSpec. You can downcast to NativeImage to access properties like uiImage (iOS).

  3. Reload the application

    main

    If you need to perform a full reload to reset the app state, use the following platform-specific shortcuts:

    • Android: Press the <kbd>R</kbd> key twice, or open the Dev Menu via <kbd>Ctrl</kbd> + <kbd>M</kbd> (Windows/Linux) or <kbd>Cmd ⌘</kbd> + <kbd>M</kbd> (macOS) and select "Reload".
    • iOS: Press <kbd>R</kbd> in the iOS Simulator.

  4. Use NitroImage hooks and views

    main

    NitroImage provides React components and hooks for easy integration into React Native applications.

    useImage()

    Asynchronously loads an image from a source and returns it as React state.

    useImageLoader()

    Creates an asynchronous ImageLoader that can be passed to <NitroImage /> to defer loading.

    <NitroImage /> (Recommended)

    A view that renders an Image either synchronously (if passed an instance) or asynchronously (if passed an ImageLoader).

    <NativeNitroImage />

    The underlying native component. Use this only if you cannot use the <NitroImage /> abstraction.

    // Using useImage
function App() {
  const image = useImage({ filePath: '/tmp/image.jpg' })
  return <NitroImage image={image} style={{ width: 400, height: 400 }} />
}

// Using useImageLoader (Deferred loading)
function App() {
  const loader = useImageLoader({ filePath: '/tmp/image.jpg' })
  return (
    <NitroImage
      image={loader}
      style={{ width: 400, height: 400 }}
    />
  )
}

// Using the native component directly
function App() {
  const image = ...
  return (
    <NativeNitroImage
      image={image}
      style={{ width: 400, height: 400 }}
    />
  )
}

  5. Install react-native-nitro-image

    main

    Install the core package and its dependency react-native-nitro-modules via npm. Note that because NitroImage uses Nitro Views, you must enable the React Native New Architecture for this library to work.

    After installing, ensure you run pod install in your iOS directory.

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

  9. Build and run the app on iOS

    main

    To run the app on iOS, you must first ensure CocoaPods dependencies are installed.

    1. Install CocoaPods via Ruby bundler (only required for the first setup):
    bundle install
    1. Navigate to the ios directory:
    cd ios
    1. Install native dependencies (run this whenever you update native modules):
    bundle exec pod install
    1. Run the app from the project root:
    bun run ios
    bundle install && cd ios && bundle exec pod install && cd .. && bun run ios

  10. Configure SDWebImage modular headers in Podfile

    main

    If you are using react-native-nitro-web-image, you must manually enable modular headers for SDWebImage in your iOS Podfile to support static linkage.

    target '...' do
  config = use_native_modules!

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

  12. Handle dynamic aspect ratios with NitroImage

    main

    To prevent layout jumps, use the width and height properties of the loaded image object to calculate the aspect ratio for your view.

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