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.
// 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 |
---|---|---|---|
anticipation | TwicPics 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. | Number | 0.2 |
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
Lazy Loading
TwicImg
will lazy-load images by default and "anticipate" lazy loading by a factor of the actual viewport. This can be controlled using the anticipation option.
When embedding TwicImg
in a lazily loading-compatible Component like FlatList, it is recommended to disable TwcImg
's lazy-loading feature using the eager
prop:
// MyComponent.jsx
import React from 'react';
import { FlatList, View, Image } from '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 Props
<TwicImg
src="<path>"
alt="<String>"
anchor="<String>"
focus="<auto|coordinates>"
eager="<boolean>"
mode="<contain|cover>"
placeholder="<preview|maincolor|meancolor|none>"
preTransform="<String>"
ratio="<ratio>"
refit="<boolean|String>"
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 | |
eager | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | boolean | false |
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 |
refit | Reframes 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 String | false |
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 |