React Native

Use TwicPics React Native Components to get images and videos integration best practices out-of-the-box.

Platform Compatibility

AndroidiOSWeb
[x][x][x]

Installation

Installing TwicPics Components

Add the @twicpics/components package to your React Native project:

# Using yarn
yarn add @twicpics/components

# Or using npm
npm install @twicpics/components

If you plan to use image caching or TwicVideo, you will also need to install additional Expo Modules. If not, proceed directly to setup section.

Installing Expo modules

The installation process for additional Expo modules depends on your project's origin, whether Expo Go or React Native CLI.

For React Native Expo Go projects

Since Expo is already installed, add the required dependencies as follows, depending on your needs:

# Expo AV installation (required for TwicVideo component)

## Using yarn
yarn add expo-av

## Or using npm
npm install expo-av
# Expo Image installation (required for image caching)

## Using yarn
yarn add expo-image

## Or using npm
npm install expo-image

Once completed, proceed to setup section.

For React Native CLI projects

First, install and configure the Expo package.

npx install-expo-modules@latest

Note: If the command fails, please refer to Expo Modules documentation.

After Expo package is installed and configured, add the required dependencies as follows, depending on your needs:

# Expo AV installation (required for TwicVideo component)

## Using yarn
yarn add expo-av

## Or using npm
npm install expo-av
# Expo Image installation (required for image caching)

## Using yarn
yarn add expo-image

## Or using npm
npm install expo-image

For iOS targeting, reinstall the project's CocoaPods:

npx pod-install

Setup

Setting-up TwicPics Components in your React Native project

You will need a TwicPics domain to initialize the package. Create an account for free to get your domain.
// App.js

import { installTwicPics } from '@twicpics/components/react-native';

installTwicPics({
  "domain": `https://<your-domain>.twic.pics/`,
});

export default function App() {
  return (
    // your app code
  )
}

For an exhaustive list of options, see Setup Options.

Setup Options

OptionDescriptionTypeDefault
anticipationTwicPics will lazy-load images by default. To avoid a too abrupt transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting.Number0.2
cachePolicyDetermines whether to cache images and where: no caching, on disk, in memory or both. Possible values are respectively none, disk, memory or memory-disk. When using a value different from none, you need to add Expo Image as a dependency to your project (see Installing Expo Modules).Stringnone
domainThis is your very own TwicPics domain. Providing it is mandatory.String
envCan be debug, offline or production. When set to debug, a gray lightweight svg placeholder that displays its intrinsic dimensions is displayed in place of all medias targeted by their src value. When set to offline, these medias are replaced by a simple placeholder that allows to visualise their display area.String"production"
maxDPRTwicPics will take the "Device Pixel Ratio" (DPR) of the current device into consideration when determining the sizes of images to load. By default, it will not take a DPR greater than 2 into consideration. If the DPR of the device is higher than 2, TwicPics will assume it to be 2. Using maxDPR, you can lower this limit down to 1 or be more permissive (for instance by setting it to 3 or 4).Number2
pathPath to prepend to all src attributes. For instance, if path is "some/folder" then a src attribute set to "image.jpg" will be expanded into "some/folder/image.jpg"String
stepTo avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio.Integer10

Usage

Basic usage

// MyComponent.jsx

import { TwicImg, TwicVideo } from '@twicpics/components/react-native'

const MyComponent = () => (
  <TwicImg
    src="image.jpg"
    style={styles.customImage}
    mode="cover"
    placeholder="preview"
  />
  <TwicVideo
    src="video.mp4"
    style={styles.customVideo}
    mode="cover"
    placeholder="preview"
  />
)

const styles = StyleSheet.create({
  customImage: {
    // some styles
  },
  customVideo: {
    // some styles
  },
})

export default MyComponent

Image Caching

By default, the <TwicImg> component only manages image caching for web platform.

If you plan to use image caching for iOS or Android platforms, you'll need to install Expo Image as a dependency of your project and configure the cache policy as follows:

// App.js

import { installTwicpics } from '@twicpics/components/react-native';

// defines the cache policy for the entire application during setup
installTwicpics({
  "domain": `https://<your-domain>.twic.pics/`,
  "cachePolicy": `disk`, // set the cache policy to 'disk' for persistent storage
});
// MyComponent.jsx

import { TwicImg } from "@twicpics/components/react-native";

const MyComponent = () => (
  <View>
    <TwicImg 
      src="path/to/your/image" {/* image will be cached to disk as defined in setup options */}
    />
    <TwicImg
      src="path/to/your/image"
      cachePolicy="memory" {/* overrides setup option with `memory` value for in-memory caching  */}
    />
    <TwicImg
      src="path/to/your/image"
      cachePolicy="none" {/* overrides setup option with `none` value: image will not be cached */}
    />
  </View>
);

For more information about the possible cachePolicy values, please refer to the Expo Image documentation.

Lazy Loading

TwicImg and TwicVideo will lazy-load assets by default and "anticipate" lazy loading by a factor of the actual viewport. This can be controlled using the anticipation option.

When embedding TwicImg or TwicVideo in a lazily loading-compatible Component like FlatList, it is recommended to disable TwicImg or TwicVideo's lazy-loading feature using the eager prop:

// MyComponent.jsx

import React from 'react';
import { FlatList, View } from 'react-native';
import { TwicImg } from '@twicpics/components/react-native'

const data = [
  // Data containing image URLs
  { id: 1, imageUrl: 'image1.jpg' },
  { id: 2, imageUrl: 'image2.jpg' },
  // More data...
];

const renderItem = ({ item }) => (
  <View>
    <TwicImg
      src={item.imageUrl}
      eager {/* disables lazy loading for this image */} />
  </View>
);

const MyComponent = () => {
  return (
    <FlatList
      data={data}
      renderItem={renderItem}
      keyExtractor={(item) => item.id.toString()}
      // Other FlatList props...
    />
  );
};

export default MyComponent;

Refit Example

The <TwicImg> component allows to reframe your image on the main subject(s) it contains.

In cover mode, the resulting image will respectratio while maximizing the area occupied by the main subject(s).

In contain mode, the image will be cropped as close as possible to the main subject(s).

To activate automatic cropping, simply add the refit property to your component.

By default, the subject will be placed at the center of the resulting image but it is possible to align the subject with a given border by specifying an anchor.

Also by default, the subject will touch the borders of the resulting image. This can be avoided by setting refit with a comma-separated length value defining padding.

For example:

  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" />

Working with ratio="none"

Particularly useful when creating hero banner, you can specify the height of your image while respecting its natural aspect ratio and optimizing the Cumulative Layout Shift metric. When using ratio="none" your style must specify the image height.

// MyComponent.jsx

import { TwicImg } from '@twicpics/components/react-native'

const MyComponent = () => (
  <TwicImg src="path/to/your/image" ratio="none" style={styles.heroImage} />
)

// When using `ratio="none"`, you are responsible for properly sizing the component
const styles = StyleSheet.create({
  heroImage: {
    height: 500,
  },
})

export default MyComponent

Components Properties

TwicImg

This component can be used in place of an <Image> component.

<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  cachePolicy="<none|disk|memory|memory-disk>" 
  eager="<boolean>"
  focus="<auto|coordinates>"
  mode="<contain|cover>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  refit="<boolean|String>"
  step="<integer>"
  style="<Object>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<Function>"
/>
AttributeDescriptionTypeDefault
altalt attribute contentString
anchorPositions the image in both contain and cover mode. Accepted values are top, bottom, left, right, top-left, top-right, bottom-left and bottom-right. position and focus take precedence in contain and cover mode respectively. Please note that anchor is applied after an eventual preTransform.String
cachePolicyOverrides the global cache policy configuration and determines whether to cache the image and where: no caching, on disk, in memory or both. Possible values are respectively none, disk, memory or memory-disk. When using a value different from none, you need to add Expo Image as a dependency to your project (see Installing Expo Modules).Stringnone
eagerLoad the image as soon as the component is mounted. This effectively means disabling lazy loading for this image.booleanfalse
focusSets the focus point in cover mode. focus takes precedence over anchor when both are provided. See the TwicPics focus attribute documentation for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with focus="auto": if you only need border-based positionning (top, bottom, left, right, etc), use anchor instead.String
modeCan be contain or cover and determines if the image fills the area and is cropped accordingly (cover) or if the image will sit inside the area with no cropping (contain).Stringcover
placeholderCan be preview, meancolor, maincolor or none. See the TwicPics output transformation documentation for more information. Setting will be overridden to none when using zoom transition.Stringpreview
preTransformA slash-separated list of TwicPics API transformations to be performed before resizing the image (see the TwicPics Manipulation documentation). Note that anchor and focus are applied after preTransform: if you need to specify a specific focus point for your preTransform then it needs to be part of the expression (like preTransform="focus=auto/crop=50px50p" for instance). Be aware that using this option can lead to unexpected results so use with caution!String
ratioA unitless width/height or width:height value pair (as in 4/3 or 4:3) that defines the aspect ratio of the display area. If height is not specified, it is assumed to be 1. A square area will be created by default. When set to none, ratio is determined based on width and height as computed by the browser following your CSS definitions. You are responsible for properly sizing the component when ratio="none".String1
refitReframes the image to maximize the area occupied by the main object(s) while respecting ratio in cover mode. Crops the image as close as possible to the main object(s) in contain mode. Can be true, false or a list of comma-separated length defining padding. See the TwicPics refit documentation for more information.boolean or Stringfalse
srcPath to the image.String
stepSee the TwicPics step attribute documentation for more information.Integer10
styleAccepts styles defined in a JavaScript object in the usual React Native style, see React Native docs.Objectnull
transitionDetermines how the image will be revealed once loaded. With a fade in effect (fade), a zoom effect (zoom) or without any transition (none). Unsupported values are handled as fade.Stringfade
transitionDurationDuration of the transition effect.String400ms
transitionTimingFunctionReact Native Easing function applied to the transition effect.Functionease
transitionDelayTransition delay of the transition effect.String0ms

TwicVideo

<TwicVideo
  src="<path>"
  anchor="<String>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<coordinates>"
  mode="<contain|cover>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  step="<integer>"
  style="<Object>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
AttributeDescriptionTypeDefault
anchorPositions the video in both contain and cover mode. Accepted values are top, bottom, left, right, top-left, top-right, bottom-left, bottom-right and center. position and focus take precedence in contain and cover mode respectively. Please note that anchor is applied after an eventual preTransform.String
durationLimits the duration of the video. duration is expressed in seconds and must be a positive number. duration will not move the starting point of the video: to do so, you'll have to use the from property. See duration documentation.String or number
eagerLoad the video as soon as the component is mounted. This effectively means disabling lazy loading for this video.booleanfalse
focusSets the focus point in cover mode. focus takes precedence over anchor when both are provided. See the TwicPics focus attribute documentation for more information. Only use this attribute if you need a specific focus point: if you only need border-based positionning (top, bottom, left, right, etc), use anchor instead.String
fromMoves the starting point of the video. from is expressed in seconds and must be a positive number. from will not move the end point of the video: to do so, you'll have to use the duration or to properties. See from documentation. See from documentation.String or number
modeCan be contain or cover and determines if the video fills the area and is cropped accordingly (cover) or if the video will sit inside the area with no cropping (contain).Stringcover
placeholderCan be preview, meancolor, maincolor or none. See the TwicPics output transformation documentation for more information. Setting will be overridden to none when using zoom transition.Stringpreview
posterFromDetermines which frame of the source video should be used as a poster / preview. posterFrom is expressed in seconds and must be a positive number. By default posterFrom is equal to 0, meaning the very first frame of the video is used. posterFrom will not modify the video in any way: to do so, you'll have to use the duration, from or to properties.String or number
preTransformA slash-separated list of TwicPics API transformations to be performed before resizing the video (see the TwicPics Manipulation documentation). Note that anchor and focus are applied after preTransform: if you need to specify a specific focus point for your preTransform then it needs to be part of the expression (like preTransform="focus=auto/crop=50px50p" for instance). Be aware that using this option can lead to unexpected results so use with caution!String
ratioA unitless width/height or width:height value pair (as in 4/3 or 4:3) that defines the aspect ratio of the display area. If height is not specified, it is assumed to be 1. A square area will be created by default. When set to none, ratio is determined based on width and height as computed by the browser following your CSS definitions. You are responsible for properly sizing the component when ratio="none".String or number1
srcPath to the video.String
stepSee the TwicPics step attribute documentation for more information.Integer10
styleAccepts styles defined in a JavaScript object in the usual React Native style, see React Native docs.Objectnull
toMoves the end point of the video. to is expressed in seconds and must be a positive number. to will not move the starting point of the video: to do so, you'll have to use the from property. See to documentation.String or number
transitionDetermines how the image will be revealed once loaded. With a fade in effect (fade), a zoom effect (zoom) or without any transition (none). Unsupported values are handled as fade.Stringfade
transitionDurationDuration of the transition effect.String400ms
transitionTimingFunctionReact Native Easing function applied to the transition effect.Functionease
transitionDelayTransition delay of the transition effect.String0ms
responsive images

The All-In-One Toolbox For Your Medias

The simplest, most powerful way to tackle responsive images & videos