Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wkovacs64/react-native-responsive-image-view

React Native component for scaling an Image within the parent View
https://github.com/wkovacs64/react-native-responsive-image-view

image react react-native react-native-component responsive-images view

Last synced: 5 days ago
JSON representation

React Native component for scaling an Image within the parent View

Awesome Lists containing this project

README 

        
# react-native-responsive-image-view



_React Native component for scaling an `Image` within the parent `View`_



[![npm Version][npm-image]][npm-url] [![Build Status][ci-image]][ci-url]

[![Code Coverage][coverage-image]][coverage-url]



## The problem



You want to display an image in your React Native app that fills the width of its container and

scales its height according to the aspect ratio of the image. If you're coming from front-end web

development, you may be familiar with Bootstrap 3's `img-responsive` class or manually applying

`max-width: 100%` and `height: auto` to an image. Unfortunately, `auto` is not a valid value for

`height` in React Native, so that technique doesn't quite translate.



## This solution



This calculates the aspect ratio of your image for you (or uses a fixed value, if you supply one)

and provides you with the appropriate props to apply to a `View` container and an `Image` inside it

which will produce the results you're looking for. The secret sauce is setting both the `height` and

`width` attributes of the `style` prop on the `Image` to `100%` and wrapping it with a `View` that

has its [`aspectRatio`][aspectratio] style property set to match the aspect ratio you want. The

package provides both a [render prop component][render-props] and a [custom hook][custom-hooks].



## Table of Contents



- [Installation](#installation)

- [Usage](#usage)

  - [Component](#component)

  - [Hook](#hook)

- [Input](#input)

  - [Basic Inputs](#basic-inputs)

    - [onLoad](#onload)

    - [onError](#onerror)

    - [source](#source)

  - [Advanced Inputs](#advanced-inputs)

    - [aspectRatio](#aspectratio)

  - [Component-only Inputs](#component-only-inputs)

    - [Render Prop Function](#render-prop-function)

      - [component](#component)

      - [render](#render)

      - [children](#children)

- [Output](#output)

  - [prop getters](#prop-getters)

    - [`getViewProps`](#getviewprops)

    - [`getImageProps`](#getimageprops)

  - [state](#state)

  - [utils](#utils)

- [Examples](#examples)

- [Snack Playground](#snack-playground)

- [Inspiration](#inspiration)

- [Other Solutions](#other-solutions)

- [LICENSE](#license)



## Installation



Using [npm][npm]:



```shell

npm install react-native-responsive-image-view

```



> This package also depends on `react` and `react-native`. Please make sure you have those installed

> as well.



## Usage



As mentioned above, this package includes both a render prop component (the default export) and a

custom hook (a named export). They provide the same functionality, so choose whichever is most

appropriate for your project.



### Component



```jsx

import React from 'react';

import { Image, View } from 'react-native';

import ResponsiveImageView from 'react-native-responsive-image-view';



export default function MyComponent({ imageUri }) {

  return (

    

      {({ getViewProps, getImageProps }) => (

        

          

        

      )}

    

  );

}

```



**N.B.** This component doesn't render anything itself, it just calls your render function or

injected component and renders that. ["Use a render prop!"][use-a-render-prop] Just be sure to

render the `Image` inside the `View` in your `render` function.



> In addition to a literal `render` prop, it also supports the component injection and

> function-as-children patterns if you prefer. See the [Render Prop Function](#render-prop-function)

> section for details.



### Hook



```jsx

import React from 'react';

import { Image, View } from 'react-native';

import { useResponsiveImageView } from 'react-native-responsive-image-view';



export default function MyComponent({ imageUri }) {

  const { getViewProps, getImageProps } = useResponsiveImageView({

    source: { uri: imageUri },

  });



  return (

    

      

    

  );

}

```



## Input



The component takes its inputs as individual props, while the hook takes its inputs as an object

(the only parameter), but the inputs themselves are primarily the same:



### Basic Inputs



#### onLoad



> `function()` | optional, no useful default



Called after the image has been loaded (and the aspect ratio has been calculated).



#### onError



> `function(error: string)` | optional, no useful default



Called if the image could not be loaded. Called with the error message in the form of a string.



- `error`: the error message as a string



#### source



> `number`/`object` | _required_



The source for your `Image`. This can be a local file resource (the result of an `import` or

`require` statement) or an object containing a `uri` key with a remote URL as its value.



### Advanced Inputs



#### aspectRatio



> `number` | **control prop**, default: automatically calculated from image dimensions



By default, `react-native-responsive-image-view` manages this value internally based on the

dimensions of the source image. However, if more control is needed, you can pass in a fixed aspect

ratio to use instead. This is useful if you want to fit the image into a statically shaped box such

as a navigation drawer header.



### Component-only Inputs



#### Render Prop Function



This is where you render whatever you want to based on the state of

`react-native-responsive-image-view` when using the component (not applicable when using the hook).

It's just a function or component, available in a few different ways. Read Donavon West's very

opinionated but informative [post about them][faccs-and-ci] for more information. They all receive

the same props, so it is purely a stylistic choice left up to you as the consumer.



```jsx

// component injection



// render prop



// function-as-children



  {/* right here */}



```



Choose your approach by passing one of the following props:



##### component



> `component` | _optional_



This is rendered with an object passed in as `props`. Read more about the properties of this object

in the [Output](#output) section.



##### render



> `function({})` | _optional_



This is called with an object. Read more about the properties of this object in the

[Output](#output) section.



##### children



> `function({})` | _optional_



This is called with an object. Read more about the properties of this object in the

[Output](#output) section.



**N.B.** Multiple render methods should not be combined, but in the event that they are,

`react-native-responsive-image-view` will honor the following order:



1.  `component`

1.  `render`

1.  function as `children`

1.  non-functional `children` (render children normally)

1.  `null` (render nothing)



## Output



Regardless of whether you are using the component or the hook, the results are an object containing

important properties you'll need for rendering. It will be passed to the

[Render Prop Function](#render-prop-function) when using the component, and returned from the hook

invocation when using the hook. The properties of this object can be split into the following

categories:



### prop getters



> See [this blog post about prop getters][kent-prop-getters]



These functions are used to apply props to the elements that you render. This gives you maximum

flexibility to render what, when, and wherever you like. You call these on the element in question

(for example: ` Note: Snack's underlying build system, `snackager`,

> [cannot currently handle](https://github.com/expo/snack/issues/383) some TypeScript features used

> in this library, so the version showcased in the playground is pinned to the latest pre-TypeScript

> implementation. We hope the Expo team can resolve this soon, but it should still provide a useful

> environment to try out the library in the meantime.



## Inspiration



I was heavily inspired by [`react-native-flex-image`][react-native-flex-image] from

[KodeFox][kodefox] (see the [Other Solutions](#other-solutions) section) with regards to how to

display the image to get the desired behavior. The original implementation and API were primarily

inspired by [Michael Jackson][mjackson]'s ["Use a Render Prop!"][use-a-render-prop] post and video,

as well as [Kent C. Dodds][kentcdodds]' [introduction to prop getters][kent-prop-getters].



## Other Solutions



After scouring [npm][npm] for solutions and trying most (if not all) of them, the best option I

found was the following:



- [`react-native-flex-image`][react-native-flex-image]



Unfortunately, it is too restrictive for my use cases. It renders the magic ``

combination for you, preventing you from customizing the layout. For example, it provides an

`onPress` prop if you want to make the `Image` touchable, but it wraps the `Image` in a

`TouchableOpacity` (what if I wanted a `TouchableHighlight` instead?). It also renders its own

loading indicator (an `ActivityIndicator`) as well as error messages (as `Text`). At the end of the

day, these features proved to be too opinionated.



## LICENSE



[MIT][license]



[npm-image]: https://img.shields.io/npm/v/react-native-responsive-image-view.svg?style=flat-square

[npm-url]: https://www.npmjs.com/package/react-native-responsive-image-view

[ci-image]:

  https://img.shields.io/github/actions/workflow/status/wKovacs64/react-native-responsive-image-view/ci.yml?logo=github&style=flat-square

[ci-url]:

  https://github.com/wKovacs64/react-native-responsive-image-view/actions?query=workflow%3Aci

[coverage-image]:

  https://img.shields.io/codecov/c/github/wKovacs64/react-native-responsive-image-view/main.svg?style=flat-square

[coverage-url]: https://codecov.io/gh/wKovacs64/react-native-responsive-image-view/branch/main

[aspectratio]: https://facebook.github.io/react-native/docs/layout-props#aspectratio

[render-props]:

  https://react.dev/reference/react/Children#calling-a-render-prop-to-customize-rendering

[custom-hooks]: https://react.dev/learn/reusing-logic-with-custom-hooks

[npm]: https://www.npmjs.com/

[react-native-flex-image]: https://github.com/kodefox/react-native-flex-image

[snack-playground]: https://snack.expo.dev/@wkovacs64/responsiveimageview

[expo-go]: https://expo.dev/client

[kodefox]: https://github.com/kodefox

[mjackson]: https://github.com/mjackson

[use-a-render-prop]: https://medium.com/@mjackson/use-a-render-prop-50de598f11ce

[faccs-and-ci]: http://americanexpress.io/faccs-are-an-antipattern/

[kentcdodds]: https://github.com/kentcdodds

[kent-prop-getters]:

  https://kentcdodds.com/blog/how-to-give-rendering-control-to-users-with-prop-getters

[examples-directory]:

  https://github.com/wKovacs64/react-native-responsive-image-view/tree/main/examples

[license]: https://github.com/wKovacs64/react-native-responsive-image-view/tree/main/LICENSE.txt