react-native-stars
v1.2.2
Published
a versatile react native star review component with half star compatibility and custom images, star sizes, star count, star spacing, and value display.
Downloads
9,662
Maintainers
Readme
react-native-stars
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.
Table of Contents
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}
fullStar= {require('./images/starFilled.png')}
emptyStar= {require('./images/starEmpty.png')}/>
</View>
Custom Components for Stars
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
|
|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:
I've included a set in example-images if you need something basic.
Roadmap
✅Custom Components fullStar
, halfStar
, emptyStar
properties now accept component inputs rather than exclusively image inputs.
✅Display Mode Transparency non-transparent backingColor no longer required for display mode.
_ Dev Upgrades adding typescript, linting, and react best practices
_ Display Mode Interpolation marginal partial star display amounts like 0.1 and 0.9 often look 'too small' or 'too big'. This feature would use interpolation to create a more natural look and feel for partial display amounts.
_ Cycle Selection for half star selection mode - instead of two halves of a star each having its own button + update value, the entire star is one button - behaving like a 3-stage toggle when clicked in succession. Values will cycle between 0 -> 0.5 -> 1 -> 0 and will respect the default parameter on initialization.
_ Slide Selection capability - component respects a continuous user input, updating component rating state according to the half/full star granularity configuration (defaults to full star)
Contributing
Pull Requests for new features and bugfixes are welcome! :)