@react-native-community/image-editor
Version:
React Native Image Editing native modules for iOS & Android
89 lines (66 loc) • 7.58 kB
Markdown
# @react-native-community/image-editor
[![Build Status][build-badge]][build]
[![Version][version-badge]][package]
[![MIT License][license-badge]][license]
[![PRs Welcome][prs-welcome-badge]][prs-welcome]
[![Lean Core Badge][lean-core-badge]][lean-core-issue]
Image Editor Native module for React Native.
Originally extracted from React Native [`issue#23313`](https://github.com/facebook/react-native/issues/23313) and maintained by the community.
## Getting started
### Install
```shell
yarn add @react-native-community/image-editor
# or
npm install @react-native-community/image-editor --save
```
### Install Pods
```shell
npx pod-install
```
## Usage
Start by importing the library:
```ts
import ImageEditor from '@react-native-community/image-editor';
```
### Crop image
Crop the image specified by the URI param. If URI points to a remote image, it will be downloaded automatically. If the image cannot be loaded/downloaded, the promise will be rejected.
If the cropping process is successful, the resultant cropped image will be stored in the cache path, and the [`CropResult`](#result-cropresult) returned in the promise will point to the image in the cache path. ⚠️ Remember to delete the cropped image from the cache path when you are done with it.
```ts
ImageEditor.cropImage(uri, cropData).then((result) => {
console.log('Cropped image uri:', result.uri);
});
```
### `cropData: ImageCropData`
| Name | Type | Description |
| ------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `offset` | `{ x: number, y: number }` | The top-left corner of the cropped image, specified in the original image's coordinate space |
| `size` | `{ width: number, height: number }` | Size (dimensions) of the cropped image |
| `displaySize`<br>_(optional)_ | `{ width: number, height: number }` | Size to which you want to scale the cropped image |
| `resizeMode`<br>_(optional)_ | `'contain' \| 'cover' \| 'stretch' \| 'center'` | Resizing mode to use when scaling the image (iOS only, Android resize mode is always `'cover'`, Web - no support) <br/>**Default value**: `'cover'` |
| `quality`<br>_(optional)_ | `number` | A value in range `0.0` - `1.0` specifying compression level of the result image. `1` means no compression (highest quality) and `0` the highest compression (lowest quality) <br/>**Default value**: `0.9` |
| `format`<br>_(optional)_ | `'jpeg' \| 'png' \| 'webp'` | The format of the resulting image.<br/> **Default value**: based on the provided image;<br>if value determination is not possible, `'jpeg'` will be used as a fallback.<br/>`'webp'` isn't supported by iOS. |
| `includeBase64`<br>_(optional)_ | `boolean` | Indicates if Base64 formatted picture data should also be included in the [`CropResult`](#result-cropresult). <br/>**Default value**: `false` |
| `headers`<br>_(optional)_ | `object \| Headers` | An object or [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) interface representing the HTTP headers to send along with the request for a remote image. |
### `result: CropResult`
| Name | Type | Description |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uri` | `string` | The path to the image file (example: `'file:///data/user/0/.../image.jpg'`)<br> **WEB:** `uri` is the data URI string (example `'data:image/jpeg;base64,/4AAQ...AQABAA'`) |
| `path` | `string` | The URI of the image (example: `'/data/user/0/.../image.jpg'`)<br> **WEB:** `path` is the blob URL (example `'blob:https://example.com/43ff7a16...e46b1'`) |
| `name` | `string` | The name of the image file. (example: `'image.jpg'`) |
| `width` | `number` | The width of the image in pixels |
| `height` | `number` | Height of the image in pixels |
| `size` | `number` | The size of the image in bytes |
| `type` | `string` | The MIME type of the image (`'image/jpeg'`, `'image/png'`, `'image/webp'`) |
| `base64`<br>_(optional)_ | `string` | The base64-encoded image data example: `'/9j/4AAQSkZJRgABAQAAAQABAAD'`<br>if you need data URI as the `source` for an `Image` element for example, you can use `data:${type};base64,${base64}` |
For more advanced usage check our [example app](/example/src/App.tsx).
<!-- badges -->
[build-badge]: https://github.com/callstack/react-native-image-editor/actions/workflows/main.yml/badge.svg
[build]: https://github.com/callstack/react-native-image-editor/actions/workflows/main.yml
[version-badge]: https://img.shields.io/npm/v/@react-native-community/image-editor.svg
[package]: https://www.npmjs.com/package/@react-native-community/image-editor
[license-badge]: https://img.shields.io/npm/l/@react-native-community/image-editor.svg
[license]: https://opensource.org/licenses/MIT
[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg
[prs-welcome]: http://makeapullrequest.com
[lean-core-badge]: https://img.shields.io/badge/Lean%20Core-Extracted-brightgreen.svg
[lean-core-issue]: https://github.com/facebook/react-native/issues/23313