React Native Rating Bar
A React Native component for generating and displaying interactive Tap or Swipe enabled Ratings supporting custom icons from [vector icons](https://github.com/oblador/react-native-vector-icons) and images.
[](https://www.npmjs.com/package/@aashu-dubey/react-native-rating-bar) [](https://www.npmjs.com/package/@aashu-dubey/react-native-rating-bar)
[Installation](#-installation) • [Usage](#-usage) • [Examples](#-examples) • [Demo](./example)
## 🚀 Installation
Install the package using yarn or npm:
```sh
yarn add @aashu-dubey/react-native-rating-bar
```
Or
```sh
npm install --save @aashu-dubey/react-native-rating-bar
```
And you also need to install [`react-native-gesture-handler`](https://github.com/software-mansion/react-native-gesture-handler), as we're using it for Swipe/Tap gestures:
```sh
yarn add react-native-gesture-handler
```
then wrap your App's entry point with `GestureHandlerRootView` (see [official doc](https://docs.swmansion.com/react-native-gesture-handler/docs/next/installation#js)) in order for drag to rate feature to work
```JSX
export default function App() {
return (
{/* content */}
);
}
```
For more info see gesture-handler's [official Installation guide](https://docs.swmansion.com/react-native-gesture-handler/docs/installation)
## 💪🏼 Usage
### Props
#### RatingBar
| prop | default | type | description |
| -------------------------------------------------------- | ------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| rateStyles | undefined | object ([RateStyles](#ratestyless-object)) | Provide custom styles for View containing whole rating group or single rating item. |
| itemCount | 5 | number | Total number of Rating items to display. |
| minRating | 0 | number | Minimum rating value allowed. Should be `>= 0` |
| maxRating | `itemCount` | number | Miximum rating value allowed. Should be `>= minRating >= 0` |
| layoutDirection | device's layout direction | 'ltr' or 'rtl' | Layout Direction to show the ratings on, left-to-right (`ltr`) or right-to-left (`rtl`) |
| unratedColor | 'rgba(0, 0, 0, 0.38)' | string (ColorValue) | Color for items that are not rated yet, usually when `index >= rating`. |
| allowHalfRating | false | boolean | If `true`, rating will increase/decrease by fraction of `0.5` instead of default `1`. |
| direction | 'horizontal' | 'horizontal' \| 'vertical' \| 'vertical-reverse' | Direction to show the ratings items in |
| | | 'horizontal' | shows the rating items horizontally. To see them in reverse horizontally set `layoutDirection="rtl"` |
| | | 'vertical' | Shows the rating items vertically, top to bottom. |
| | | 'vertical-reverse' | Shows the rating itmes vertically, bottom to top. |
| glow | true | boolean | If true, Rating items will glow when being touched or dragged.
Note:- iOS only |
| glowColor | '#FFC107' | string (ColorValue) | Defines color for glow |
| glowRadius | 2 | number | Defines the radius of glow |
| ignoreGestures | false | boolean | Ignore user gestures to make rating bar view only
Alternatively you can use `RatingBarIndicator` component. |
| initialRating | 0 | number | Defines the initial rating to be set to the rating bar. |
| itemPadding | 0 | number | The amount of space by which to inset each rating item. |
| itemSize | 40 | number | Defines width and height of each rating item in the bar. |
| tapOnlyMode | false | boolean | If `true`, will disable drag to rate feature and only allow taps to change ratings. |
| updateOnDrag | false | boolean | Defines whether or not the [`onRatingUpdate`](#tableOnRatingUpdateProp) updates while dragging. |
| useSolution | 1 | 1 or 2 (number) | There are two implemented solutions for the drag to rate feature, choose whichever works best for you.
You won't usually notice any difference, unless ratings are vertical, see [`direction`](#tableDirectionProp) props. |
| onRatingUpdate | undefined | function(rating: number) | Return current rating whenever rating is updated.
[`updateOnDrag`](#tableUpdateOnDragProp) can be used to change the behaviour how the callback reports the update.
By Default it only returns update when the touch ends, either when tapping or dragging. |
| ratingView | undefined | object ([RatingView](#ratingviews-object)) | Properties for rating view that updates with current rating.
By default it shows `Rating: {rating} / {itemCount}` |
| itemBuilder | undefined | function(index: number) => JSX.Element | Function to return your custom components to be used as rating items, usually Image or Icon component from [react-native-vector-icons](https://github.com/oblador/react-native-vector-icons).
You can either pass single component or different components based on `index` property from param.
index - Provides Rating bar item's index position as param. |
| ratingElement | undefined | object ([RatingElement](#ratingelements-object)) | Define 3 different states of rating.
`empty`, `half` and `full`. |
##### [`ratingElement`'s Object](#tableRatingElement)
- | key | type | description |
| ----- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| empty | JSX.Element | Defines Element to be used as rating bar item when item is unrated. |
| half | JSX.Element | Defines Element to be used when as rating bar item when only half portion of item is rated.
**Note**:- [allowHalfRating](#tableAllowHalfRating) needs to be set to true |
| full | JSX.Element | Defines Element to be used when as rating bar item when item is completely rated. |
##### [`rateStyles`'s Object](#tableRateStylesProp)
- | key | type | description |
| ------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
| container | object (ViewStyle) | Custom styles for View contaning whole rating group. |
| starContainer | object (ViewStyle) \| ((index: number) => StyleProp) | Custom styles for View contaning Sigle rating item. |
##### [`ratingView`'s Object](#tableRatingView)
- | key | type | description |
| -------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| showRating | boolean | Whether to show Rating indicator. By default view doesn't show. |
| position | 'top' \| 'bottom' | Whether to show indicator on `top` or `bottom` of Rating bar. By default it shows on `top`. |
| titleText | string | Custom title that shows at the start, before `{currentRating} / {itemCount}`.
Default is `"Rating: "`. |
| containerStyle | object (ViewStyle) | Style for main view container. |
| titleStyle | object (TextStyle) | Style for text showing before ratings, at the start. |
| ratingStyle | object (TextStyle) | Style for text showing current rating. |
| totalStyle | object (TextStyle) | Style for text showing total allowed rating. |
| custom | ReactElement | Pass custom component replacing the default one, can be emoji, image or text etc.
Passing this will make above props irrelevent, except `showRating` and `position`.
Note:- You have to handle updates based on rating yourself. |
> **Note**:- To make the component work you must pass either of `itemBuilder` or `ratingElement` with valid values.
#### RatingBarIndicator
This is view only alternative to `RatingBar` with no Tap or Swipe capability and From above props **RatingBarIndicator** contains `layoutDirection`, `unratedColor`, `direction`, `itemCount`, `itemPadding`, `itemSize`, `rating` and `itemBuilder` with same specific uses.
### 📲 Examples
#### Using RatingBar Component
There are few different ways to use Rating Bar component
###### Using [`ratingElement`](#tableRatingElement) prop:
```JSX
),
half: (
),
empty: (
),
}}
onRatingUpdate={value => console.log(value)}
/>
```
Assets are available [here](./example/src/assets).
Or you can use Icon component from [react-native-vector-icons](https://github.com/oblador/react-native-vector-icons):
```JSX
,
half: ,
empty: ,
}}
onRatingUpdate={value => console.log(value)}
/>
```
###### Using [`itemBuilder`](#tableItemBuilder) prop:
```JSX
}
onRatingUpdate={value => console.log(value)}
/>
```
###### Based on [`itemBuilder`](#tableItemBuilder) prop's index param:
Passing different component in `itemBuilder` based on index param value:
```JSX
{
switch (index) {
case 0:
return (
);
case 1:
return ;
case 2:
return ;
case 3:
return ;
case 4:
return (
);
default:
return ;
}
}}
onRatingUpdate={value => console.log(value)}
/>
```
#### Using `RatingBarIndicator` Component
```JSX
}
itemCount={5}
itemSize={50}
unratedColor="rgba(255, 193, 7, 0.2)"
direction="horizontal" // Or "vertical", "vertical-reverse"
/>
```
#### Vertical Mode
| 
| 
|
| :---------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------: |
| vertical | vertical-reverse |
## 🚧 Issue
You may notice, especially in Android drag to rate is a little slower, this is a dev only problem, if you run your build on release mode or even debug with JS dev mode disabled it will run way way faster, something related to [this](https://github.com/facebook/hermes/issues/48).
That being said, I'm trying to fix this.
## 🌻 Motivation
This project was initially started as I needed to implement a rating component for [Hotel Booking UI](https://github.com/Aashu-Dubey/React-Native-UI-Templates/blob/main/react_native_UI_Templates/res/hotel/hotel_booking.png) template in my other open source project for learning [React-Native-UI-Templates](https://github.com/Aashu-Dubey/React-Native-UI-Templates), and failing to find a proper solution that works same as the original Project in Flutter, I decided to replicate the Rating library used in the Flutter project.
So this package is initially inspired from Flutter package [flutter_rating_bar](https://github.com/sarbagyastha/flutter_rating_bar) (including the demo 😅) with some extra added functionalities.
## 🙋♀️ Contributing
See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
## 📜 License
MIT