React Native

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

Installation

Add the @twicpics/components package to your project:

# Using yarn
yarn add @twicpics/components
# Or using npm
npm install @twicpics/components

Setup

Install TwicPics in your React Native project

Note that while we recommend using ES module imports, TwicPics Components is backward compatible with CommonJS and require statements.

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

Option	Description	Type	Default
`domain`	This is your very own TwicPics domain. Providing it is mandatory.	`String`
`env`	Can 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"`
`maxDPR`	TwicPics 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`).	`Number`	`2`
`path`	Path 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`
`step`	To 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.	`Integer`	`10`

Usage

Note: <TwicVideo> is not supported yet for React Native.

Basic usage

// MyComponent.jsx

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

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

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

export default MyComponent

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 Props

<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  focus="<auto|coordinates>"
  mode="<contain|cover>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  step="<integer>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<Function>"
/>

Attribute	Description	Type	Default
`alt`	`alt` attribute content	`String`	based on `src`
`anchor`	Positions 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`
`focus`	Sets 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`
`mode`	Can 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`).	`String`	`cover`
`placeholder`	Can 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`.	`String`	`preview`
`preTransform`	A 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`
`ratio`	A 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. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`.	`String`	`1`
`src`	Path to the image. When not provided, a red lightweight `svg` placeholder that displays its intrinsic dimensions is displayed in place of the absent image. When env is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder.	`String`
`step`	See the TwicPics step attribute documentation for more information.	`Integer`	`10`
`style`	Accepts styles defined in a JavaScript object in the usual React Native style, see React Native docs.	`Object`	`null`
`transition`	Determines 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`.	`String`	`fade`
`transitionDuration`	Duration of the transition effect.	`String`	`400ms`
`transitionTimingFunction`	React Native Easing function applied to the transition effect.	`Function`	`ease`
`transitionDelay`	Transition delay of the transition effect.	`String`	`0ms`

React Svelte 3

Components