a versatile react native star review component with half star compatibility and custom images, star sizes, star count, star spacing, and value display.
Switch branches/tags
Nothing to show
Clone or download
Latest commit 8511d16 Jul 30, 2018
Permalink
Failed to load latest commit information.
example-images readme fix Feb 14, 2017
.gitignore Initial commit Feb 14, 2017
LICENSE Initial commit Feb 14, 2017
README.md style updates, bug fixes Jul 31, 2018
index.js style updates, bug fixes Jul 31, 2018
package.json 1.1.5 Jul 31, 2018

README.md

react-native-stars

NPM

react-native-stars is a versatile react native star review component with half star compatibility and custom images, star sizes, star count, star spacing, and value display.

rn-stars

rn-stars-android

Table of Contents

  1. Installation
  2. Usage
  3. Basics
  4. Modes
  5. Props
  6. Image Input
  7. Contributing

Installation

npm install react-native-stars --save

Usage

Basics

For Selection

<View style={{alignItems:'center'}}>
  <Stars
    half={true}
    default={2.5}
    update={(val)=>{this.setState({stars: val})}}
    spacing={4}
    starSize={40}
    count={5}
    fullStar={require('./images/starFilled.png')}
    emptyStar={require('./images/starEmpty.png')}
    halfStar={require('./images/starHalf.png')}/>
</View>

For Display

<View style={{alignItems:'center'}}>
  <Stars
    display={3.67}
    spacing={8}
    count={5}
    starSize={40}
    backingColor='cornsilk' {/* must NOT be 'transparent' */}
    fullStar= {require('./images/starFilled.png')}
    emptyStar= {require('./images/starEmpty.png')}/>
</View>

Custom Components for Stars

custom components

import { StyleSheet } from 'react-native';
import Stars from 'react-native-stars';
import Icon from 'react-native-vector-icons/MaterialCommunityIcons';

<View style={{alignItems:'center'}}>
  <Stars
    default={2.5}
    count={5}
    half={true}
    starSize={50} {/* must be set to the size of the custom component if in selection mode */}
    fullStar={<Icon name={'star'} style={[styles.myStarStyle]}/>}
    emptyStar={<Icon name={'star-outline'} style={[styles.myStarStyle, styles.myEmptyStarStyle]}/>}
    halfStar={<Icon name={'star-half'} style={[styles.myStarStyle]}/>}
  />
</View>

const styles = StyleSheet.create({
  myStarStyle: {
    color: 'yellow',
    backgroundColor: 'transparent',
    textShadowColor: 'black',
    textShadowOffset: {width: 1, height: 1},
    textShadowRadius: 2,
  },
  myEmptyStarStyle: {
    color: 'white',
  }
});

Modes

Selection Mode

For when you want the component to respond to user input. Pressing the stars (or half stars) will call the function passed to the update property. This is the default mode. Use the default property to define a default rating on render. Use the half property to allow for half star input granularity. If a non-whole value (eg. 2.5) is passed into default and the half property isn't set to true, the default value will be truncated down to the nearest whole number.

Display Mode

For when you want to display an aggregate value. The value displayed will remain static unless updated through display property. Passing any value passed into the display property will activate this mode and override the presence of any Selection Mode specific properties. Display mode defaults to a straight bar proportion - overridden by opacity property which maps star values to opacity as a percentage instead.

Props

Prop Type Description Required Default
fullStar image or component Image of the form require('./path/to/image.png'), Component may be any valid, square React component. Yes NA
emptyStar image or component see above Yes NA
halfStar image or component see above No null
count int the total number of stars No 5
starSize int width,height of individual star No 30
default 0 <= default <= count (in Selection Mode) initial default rating, int x or x.5 (x.5 only works if half is true) No 0
update function (in Selection Mode) function to be run on a given star selection selection ex: update={(val)=> this.setState({stars: val})} No ()=>{}
spacing number pixel amount of separation between each star No 0
display 0 <= display <= count (passing any value sets to Display Mode) star value to be displayed eg. 3.6 (of 5), 7.8 (of 10) No null
backingColor string/color (in Display Mode) color behind the component (cannot be transparent) No white
opacity bool (in Display Mode) displays star values as opacity percentages (0 - 1.0) No false
half bool (in Selection Mode) allows for half star ratings No false
disabled bool Disables onPress/buttons in Selection mode No false

Image Input

Props fullStar, emptyStar, and halfStar may be either components or image files.

Custom components may be any valid, uniformly dimensioned React component / element. When using custom components in selection mode, starSize must be set, otherwise the buttons will not function properly.

Images should have transparent backgrounds (.pngs), close to uniform dimensions, consistency between images (both fullStar.png and emptyStar.png are 100px/100px). Half star images are expected to be cropped as though they were full, with the center of the image intersecting the right edge of the half star object. If you're using Adobe Illustrator you can check the 'Use Artboards' box to ensure that empty space in the artboard is included during the export to .png. Half star images can, but don't need to have full outlines - both formats below are acceptible.

example compatible images:

stars

I've included a set in example-images if you need something basic.

Contributing

Pull Requests for new features and bugfixes are welcome! :)

License

MIT License