Star Rating Component Documentation

The StarRating component is a customizable React component that allows users to rate items using stars. It supports features like half-star ratings, custom colors, animations, and more.

Installation

npm install star-meter

Make sure to include the CSS file for animations:

import "./StarRating.css";

Basic Usage

import StarRating from "star-meter";

function App() {
  const handleRating = (rating) => {
    console.log(`User rated: ${rating}`);
  };

  return <StarRating onSetRating={handleRating} />;
}

Props

| Prop | Type | Default | Description | | ---------------- | -------- | --------- | ---------------------------------------------------------- | | maxRating | number | 5 | Maximum number of stars to display | | color | string | "#fcc419" | Color of the stars | | textcolor | string | "#0d0d0d" | Color of the rating text | | size | number | 48 | Size of stars in pixels | | messages | array | [] | Array of messages to display for each rating | | className | string | "" | Additional CSS class names | | defaultRating | number | 0 | Initial rating value | | onSetRating | function | () => {} | Callback function when rating changes | | allowHalfStars | boolean | true | Enable half-star ratings | | animation | string | "none" | Animation style: "scale", "rotate", "bounce", or "none" | | allowReset | boolean | true | Allow resetting the rating by clicking the same star again |

Features

Half-Star Ratings

The component supports half-star ratings by default. Users can hover over the left or right side of a star to select a half or full star rating.

<StarRating allowHalfStars={true} />

To disable half-star ratings:

<StarRating allowHalfStars={false} />

Custom Colors

You can customize the color of the stars and the rating text:

<StarRating color="#ff6b6b" textcolor="#339af0" />

Animations

The component supports several animation styles:

<StarRating animation="scale" /> // Options: "scale", "rotate", "bounce", "none"

Make sure you've imported the CSS file for animations to work properly.

Custom Rating Messages

You can display custom messages for each rating value:

<StarRating
  maxRating={5}
  messages={["Terrible", "Bad", "Okay", "Good", "Excellent"]}
/>

The message corresponding to the current rating will be displayed next to the stars.

Reset Functionality

Users can reset the rating by clicking on the same star again:

<StarRating allowReset={true} />

To disable this feature:

<StarRating allowReset={false} />

Event Handling

The component provides a callback function that is triggered when the rating changes:

const handleRating = (value) => {
  console.log(`New rating: ${value}`);
  // Perform actions based on the new rating
};

<StarRating onSetRating={handleRating} />;

Accessibility

The component is built with accessibility in mind:

• Stars are keyboard-navigable using Tab and can be activated with Enter or Space
• Proper role attributes are applied
• Interactive elements have appropriate tabIndex values

CSS Customization

You can further customize the component with CSS by targeting the provided class names:

/* Example custom styling */
.star {
  margin: 0 2px;
}

.star.scale:hover {
  transform: scale(1.2);
}

.star.rotate:hover {
  transform: rotate(15deg);
}

.star.bounce:hover {
  animation: bounceEffect 0.3s ease;
}

@keyframes bounceEffect {
  0%,
  100% {
    transform: translateY(0);
  }
  50% {
    transform: translateY(-10px);
  }
}

Example

import React, { useState } from "react";
import StarRating from "star-rating-component";

function MovieRating() {
  const [userRating, setUserRating] = useState(0);

  return (
    <div className="movie-rating">
      <h3>Rate this movie:</h3>
      <StarRating
        maxRating={5}
        size={32}
        color="#ffd700"
        defaultRating={userRating}
        onSetRating={setUserRating}
        messages={["Poor", "Fair", "Good", "Very good", "Excellent"]}
        animation="scale"
      />
      {userRating > 0 && <p>You rated this movie: {userRating} stars</p>}
    </div>
  );
}

Internal Structure

The component consists of two main parts:

1. The StarRating container component that manages state and handles events
2. The Star component that renders individual stars

Browser Support

The component should work in all modern browsers that support React and SVG.

License

MIT