react-native-cloudimage-cloud

Requirements

Cloudimage account

To use the Cloudimage Cloud plugin, you will need a Cloudimage token to deliver your images over CDN. Don't worry, it only takes seconds to get one by registering here. Once your token is created, you can configure it as described below. This token allows you to use 25GB of image cache and 25GB of worldwide CDN traffic per month for free.

Installation

To start using this plugin simply add it to your project with the package manager of your choice.

yarn add react-native-cloudimage-cloud

OR

npm install react-native-cloudimage-cloud

Setup

Before you can use any of the components you should configure the plugin with setPluginConfig. See next table for an exhaustive list of configuration object.

// App.tsx

setPluginConfig(config);

export default function App() {
//
}

Configuration object

| Property | Type & Default | Description | | :---------------------: | :--------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | token | string : '' | Required. Your Cloudimage customer token. Subscribe for a Cloudimage account to get one. The subscription takes less than a minute and is totally free. | | placeholderBackground | string : '#f4f4f4' | Placeholder coloured background while the image is loading. Can be set to a valid URL in order do display some other resource (image, git, etc.) to display while main resource is loading. | | domain | string : 'cloudimage.io' | Change this if you use a custom CNAME for your Cloudimage integration. | | baseUrl | string : '/' | Your image folder on server; this alows to shorten your origin image URLs. | | limitFactor | number : 100 | Rounds up the size of the image to the nearest limitFactor value (for an image with width 358px and limitFactor equal to 100, the plugin will round up to 400px). | | doNotReplaceURL | boolean : false | If set to true, the plugin will only add query parameters to the provided image source URL. | | devicePixelRatioList | number[] : [1, 1.5, 2] | List of supported device pixel ratios. If there is no need to support retina devices, you should set empty array. | | lazyLoading | boolean : true | If set to true plugin will lazy load requested resources. | | lazyInterval | number : 1000 | Interval used to check users viewport. Lower values means more frequent checks. | | lazyThreshold | number : 50 | Threshold between users viewport and resource. Higher values means that resource will load earlier. |

Once that's done you can start using plugin components in your application.

Basic example

Below example will show a basic usage of the plugin with help of CloudImage component.

// SomeComponent.tsx

// imports...

setPluginConfig({
  baseUrl: 'https://samples.scaleflex.com/',
  domain: 'cloudimg.io',
  token: 'doc',
});

export default function SomeCopmponent() {
  return (
      <View style={styles.container}>
        <CloudImage
          src="hotel.jpg"
          style={styles.image}
          filters={{ blur: 1, colorOverlay: { color: 'white' } }}
          watermarks={{
            addWatermark: true,
            text: 'global',
            multipleWatermarks: [
              { addWatermark: true, text: 'first' },
            ],
          }}
          operations={{
            function: 'bound',
            verticalFlip: true,
            radius: {
              topLeft: 0,
              topRight: 'max',
              bottomLeft: 'max',
              bottomRight: 'max',
            },
            backgroundColor: '000000',
          }}
        />
      </View>

  );
}

const styles = StyleSheet.create({
  container:{
    // Some container styles
  }

  image: {
   // Some image styles
  },
});

Components

CloudImage

Properties

| Property | Type : Default | Description | | :---------------------: | :-----------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | src | string : undefined | Image source. | | alt | string : equal to src | Image alt. | | crossOrigin | string : 'anonymous' | Cross-Origin Resource Sharing. MDN documents. Possible values: 'anonymous', 'use-credentials'. | | referrerPolicy | string : 'strict-origin-when-cross-origin' | Referrer policy MDN docs. Possible values: 'no-referrer', 'no-referrer-when-downgrade', 'origin', 'origin-when-cross-origin', 'same-origin', 'strict-origin', 'strict-origin-when-cross-origin', 'unsafe-url'. | | limitFactor | number : taken from configuration object | Use to specify some value that is different from global config. | | autoResize | boolean : true | Automatically determine best image sizes. Sets width and height property of operations object. | | placeholderBackground | string : taken from configuration object | Use to specify some value that is different from global config. | | style | ImageStyle : undefined | CSS styles passed to image. | | operations | OperationsPropertiesIntreface or string : undefined | Use to apply some image transformations before delivering. | | watermarks | See WatermarksPropertiesIntreface or string : undefined | Use to add watermarks to a image before delivering. | | filters | See FiltersPropertiesIntreface or string : undefined | Use to apply some filters to a image before delivering. |

OperationsPropertiesIntreface

You can use plain string instead of object as well. See Cloudimage documents for more examples.

| Property | Type | Description | | :-------------------: | :--------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | width | number | Image width. | | height | number | Image height. | | function | string | Resize function. Possible values: 'crop', 'face', 'cropfit', 'bound', 'fit', 'boundmin', 'cover', 'facehide' | | preventEnlargement | boolean | Disallows image upscaling when resizing with the width or height operations. When resizing, the image can be either scaled down or up depending on the original and target dimensions. | | rotate | number | Rotates the image by a specified angle, counterclockwise. | | trim | number | Removes any single-color padding around the image if present. The parameter does not specify the amount of border or frame to trim but rather how aggressive the trim algorithm should be. A bigger value of the parameter (e.g. 25) might trim part of the image. Typical values are between 0 and 10. | | removeBackgound | boolean | Background removal automatically detects the foreground object and isolates it by removing the background of an image using advanced AI technology. | | margin | number | Defines a minimum margin when fitting the image in the new canvas. Used with function: 'fit'. | | upscaleImage | boolean | Allows upscaling smaller images to the desired dimensions (will result in inferior image resolution). Used with function: 'fit'. | | blurBackground | boolean | Sets blurred image background. Used with function: 'fit'. | | blurBackgroundValue | number | Applies Gaussian blur to the background image. Used with function: 'fit'. | | backgroundOpacity | number | Specifies background image opacity. Used with function: 'fit'. | | backgroundTintColor | number | Defines a color to tint the background image. Used with function: 'fit'. | | backgroundColor | string | Color in hexadecimal format or basic color f.e. red. Used with function: 'fit'. | | devicePixelRatio | number | Allows you to deliver the proper image dimensions according to a defined device pixel ratio. This operation can help with conversion between device-independent pixels and CSS (reference) pixels. | | backgroundGravity | string | Defines the positioning of the background image within its container. Possible values: 'north', 'northwest', 'northeast', 'west', 'centre', 'center', 'east', 'southwest', 'south', 'southeast', 'trim'. Used with function: 'fit'. | | horizontalFlip | boolean | Mirrors the image horizontally. | | verticalFlip | boolean | Mirrors the image vertically. | | operationGravity | string or OperationFocalPointInterface | Sets the position of the image in the fit box. Possible values: 'north', 'northwest', 'northeast', 'west', 'centre', 'center', 'east', 'southwest', 'south', 'southeast', 'trim', 'auto', 'face', 'trim', 'smart' or OperationFocalPointInterface. Used with function: 'fit'. | | positionableCrop | OperationPositionableCropInterface | Allows to crop an image by providing the exact cropping area. It is useful when you want to crop a specific part of the image. | | faceMargin | number or CoordinatesInterface | To control the margin when cropping the face out. Used with function: 'facehide' | | aspectRatio | OperationAspectRatioInterface | Sets target aspect ratio or aspect ratio range when cropping. | | radius | number or OperationRadiusInterface | Rounds the corners of images. |

WatermarksPropertiesIntreface

You can use plain string instead of object as well. See Cloudimage documents for more examples.

| Property | Type | Description | | :------------------: | :------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | addWatermark | boolean | Set to 'true' to enable watremarking. | | opacity | number | Defines watermark opacity. | | url | string | The URL of the watermark image. Can be URL-encoded. Required for external watermark type. | | text | string | Any text that you want to be displayed. Required for text watermark type. | | font | string | Font family to be used for text watermark. | | textColor | string | Color in hexadecimal format or basic color f.e. red. | | watermarkGravity | string | Defines the position to "anchor" the watermark to. Possible values: 'north', 'northwest', 'northeast', 'south', 'southwest', 'southeast', 'east', 'west', 'absolute', 'realtive', 'center'. | | padding | WatermarkPaddingInterface | Adds padding from the anchoring point. | | position | WatermarkPositionInterface | Sets the position in percent from the resized image. Works only with: watermarkGravity: 'absolute', 'relative' | | scale | WatermarkScaleInterface | Watermark image scaling defined in in percent of the watermark dimensions. | | fontSize | WatermarkFontSizeInterface | Sets the font size. | | multipleWatermarks | WatermarkPropertiesIntreface[] | Used to define multiple watermarks. If array is not empty all above settings will be used as global settings for all individual watermark. |

FiltersPropertiesIntreface

You can use plain string instead of object as well. See Cloudimage documents for more examples.

| Property | Type | Description | | :------------: | :--------------------------------------------------------------: | :--------------------------------------------------------------- | | brightness | number | Adjusts the brightness of the image. | | contrast | number | Adjusts the contrast of the image. | | saturate | number | Adjusts the saturation of the image. | | grayScale | number | Converts the image to a black and white one. | | pixelate | number | Pixelates the image into X-pixel-sized blocks. | | blur | number | Applies Gaussian blur. | | sharpen | number | Applies unsharp mask to sharpen the image. | | colorOverlay | FilterColorOverlayInterface | Applies a color overlay. | | faceBlur | FilterFaceBlurInterface | Detects all faces in the image and applies blur to conceal them. |

OperationPositionableCropInterface

| Property | Type | Description | | :-----------: | :----------------------------------------------: | :--------------------------------------------------------------------- | | topLeft | CoordinatesInterface | Coordinate of the top left crop rectangle point. Set only one. | | bottomRight | CoordinatesInterface | Coordinate of the bottom right crop rectangle point. Set only one. | | center | CoordinatesInterface | Coordinate of the center crop rectangle point. Set only one. |

CoordinatesInterface

| Property | Type | Description | | :------: | :------: | :-------------------------- | | x | number | Required. X coordinate. | | y | number | Required. Y coordinate. |

OperationAspectRatioInterface

| Property | Type | Description | | :------: | :----------------------: | :--------------------------------------------------------------------------- | | from | number or string | Required. Minimum ascpect ratio of an image (string examle: '16:9'). | | to | number or string | Maximum ascpect ratio of an image. (string examle: '16:9'). |

OperationRadiusInterface

| Property | Type | Description | | :-----------: | :----------------------: | :-------------------------------------------------------------- | | topLeft | number or string | Radius of the top left image corner. Can be set to 'max'. | | topRight | number or string | Radius of the top right image corner. Can be set to 'max'. | | bottomRight | number or string | Radius of the bottom right image corner. Can be set to 'max'. | | bottomLeft | number or string | Radius of the bottom left image corner. Can be set to 'max'. |

OperationFocalPointInterface

| Property | Type | Description | | :---------------: | :------: | :-------------------------------------------------------------------------------- | | coordinatesType | string | Type of the coordinate. Possible values: 'pixels', 'percentage', 'coefficient'. | | x | number | Required. X coordinate. | | y | number | Required. Y coordinate. |

WatermarkPaddingInterface

| Property | Type | Description | | :------: | :------: | :------------------------------------------------------------------- | | x | number | Required. X coordinate. | | y | number | Y coordinate. | | xType | string | Type of the x coordinate. Possible values: 'pixels', 'percentage'. | | yType | string | Type of the y coordinate. Possible values: 'pixels', 'percentage'. |

WatermarkPositionInterface

| Property | Type | Description | | :------: | :------: | :-------------------------- | | x | number | Required. X coordinate. | | y | number | Y coordinate. |

WatermarkScaleInterface

| Property | Type | Description | | :----------: | :------: | :------------------------------------------------------------------------ | | scaleValue | number | Required. Watermark scaling value. | | scaleType | string | Type of the watermark scaling. Possible values: 'pixels', 'percentage'. |

WatermarkFontSizeInterface

| Property | Type | Description | | :------: | :-------: | :--------------------------------------------------------------------- | | size | number | Required. Watermark font size. | | max | boolean | If set to true watermark size changes dynamically with max of size |

FilterColorOverlayInterface

| Property | Type | Description | | :--------: | :------: | :------------------------------------------------------------------------------------------------------------------------------------ | | color | string | Required. Color of the color overlay in hexadecimal format or basic color f.e. red. | | opacity | number | Required. Color opacity. |

FilterFaceBlurInterface

| Property | Type | Description | | :------: | :-------: | :---------------- | | enable | boolean | 'true', 'false' | | radius | number | Blur radius. | | sigma | number | Blur sigma. |