https://github.com/teddy95/starry
JavaScript star rating system 🌟🌃💖
https://github.com/teddy95/starry
cookie css icons javascript js npm rating star star-rating starrating starry
Last synced: about 1 year ago
JSON representation
JavaScript star rating system 🌟🌃💖
- Host: GitHub
- URL: https://github.com/teddy95/starry
- Owner: Teddy95
- License: other
- Created: 2014-06-04T09:11:51.000Z (about 12 years ago)
- Default Branch: master
- Last Pushed: 2020-07-26T12:11:13.000Z (almost 6 years ago)
- Last Synced: 2024-04-14T05:10:53.255Z (about 2 years ago)
- Topics: cookie, css, icons, javascript, js, npm, rating, star, star-rating, starrating, starry
- Language: JavaScript
- Homepage: https://teddy95.github.io/Starry
- Size: 35.6 MB
- Stars: 18
- Watchers: 3
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Starry 🌟🌃💖
[Starry Documentation](https://teddy95.github.io/Starry)
## Installation
Include Starry scripts and stylesheets in your html DOM:
```html
```
```html
```
Or install Starry as a Node dependency:
```bash
$ npm install starry-rating
```
```javascript
import Starry from 'starry-rating'
// or with require...
const Starry = require('starry-rating')
```
## How to use
### HTML markup
```html
```
### JavaScript API
```javascript
var starRatingEl = document.getElementById('star-rating');
var starRating = new Starry(starRatingEl);
```
#### More complex example
More complex example of a star rating with tooltips and custom icons, which is logging the rating to console. Tooltips have to be rendered in ```onRender()``` method by any tooltip library. In this example we use Bootstrap tooltips with jQuery & Popper.js.
```javascript
var starRatingId = 'ExampleRating'; // Html DOM id + star rating element name
var starRatingEl = document.getElementById(starRatingId);
var starRating = new Starry(starRatingEl, {
name: starRatingId, // Use a name to determine tooltips for only this Starry element
labels: [
'Low',
'Nice to have',
'Very nice',
'Perfect',
'Excellent'
],
onClear: function () {
$('[data-name="' + starRatingId + '"] [data-tooltip]').tooltip('dispose');
},
onRender: function () {
$('[data-name="' + starRatingId + '"] [data-tooltip]').tooltip({
trigger: 'hover',
placement: 'top'
});
},
onRate: function (rating) {
console.log(rating)
},
icons: {
// File path, uri or base64 string for `src` attribute
blank: './dist/icons/blank.svg',
hover: './dist/icons/hover.svg',
active: './dist/icons/active.svg'
}
});
```
#### Options
| Option | Type | Default | Description |
| ------------------- | --------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| name | String | | Name of star rating element. This option is required, if multi rating is disabled. |
| stars | Integer | `5` | Number of rating stars. |
| multiRating | Boolean | `true` | Determines whether the user can submit several ratings. |
| beginWith | Float | `0` | Preloaded rating in percentage. |
| readOnly | Boolean | `false` | Read only rating stars. |
| staticActiveRating | Boolean | `true` | Show current rating while hovering over rating stars. |
| setStarsAfterRating | Boolean | `true` | Update rating stars after rating to new value. |
| labels | Array / Boolean | `false` | Labels / tooltips for the stars. |
| onRate | Function | `(rating) => true` | Called on rating event. |
| onClear | Function | `undefined` | Called each time when Starry is being destroyed or rebuilt. |
| onRender | Function | `undefined` | Called each time when Starry is build / rendered in html DOM. |
| icons | Object | Default [Starry icons](/dist/icons). | Icon images. Object with properties `blank` (), `active` () and `hover` (). Use a string for each image source. |
#### Methods
##### Get current rating `getCurrentRating()`
```javascript
console.log(starRating.getCurrentRating())
```
##### Destroy Starry `clear()`
```javascript
starRating.clear()
```
##### Update Starry with new configurations `update(config)`
Starry will merge the new configurations into the old ones.
```javascript
starRating.update({
readOnly: true,
beginWith: 50
})
```
##### Attach event listener `on(eventName, callbackFunction)`
Attach an event listener to the star rating.
```javascript
starRating.on('rate', function (rating) {
console.log('Rating: ' + rating)
})
```
#### Events
| Name | Arguments | Description |
| ------ | --------- | -------------------- |
| rate | `rating` | Fired on rating. |
| render | | Fired on rendering. |
| clear | | Fired on destroying. |
## Cookies
Starry use [cookies](http://en.wikipedia.org/wiki/HTTP_cookie), to save ratings! 🍪
## License
The MIT License (MIT) - [View LICENSE.md](LICENSE.md)
## Resources
- [Starry v3.1.3 Documentation](https://teddy95.github.io/Starry/v3.1.3)