React Star Rating Component

A highly customizable and lightweight star rating component for React applications. Supports both full and half-star ratings with extensive customization options.

🚀 Features

• ⭐ Configurable number of stars
• 🌟 Support for half-star ratings
• 🔄 Deselectable ratings (click same rating to cancel)
• ✨ Interactive hover effects
• 🔒 Read-only mode support
• 🎨 Customizable star colors
• 📐 Adjustable star sizes
• 🎯 TypeScript support
• 🪶 Lightweight

📦 Installation

Using npm

npm install react-flexible-star-rating

Alternatively, you can use yarn or pnpm:

Using yarn

yarn add react-flexible-star-rating

Using pnpm

pnpm add react-flexible-star-rating

💻 Basic Usage

Using a Callback Function

This example demonstrates how to handle rating changes using a custom callback function. The rating value is logged to the console, and if the user clicks the same rating again, it resets to 0.

import { StarRating } from 'react-flexible-star-rating';

function App() {
  const handleRatingChange = (rating: number) => {
    // Logs the new rating; resets to 0 if the same rating is clicked again
    console.log(`New rating: ${rating}`);
  };

  return <StarRating initialRating={3.5} onRatingChange={handleRatingChange} />;
}

Using State with a Handler Function

This example demonstrates how to manage the rating value using the useState hook. The handleRatingChange function updates the state when the user selects a new rating.

import { useState } from 'react';
import { StarRating } from 'react-flexible-star-rating';

function App() {
  const [rating, setRating] = useState(3.5);

  const handleRatingChange = (newRating: number) => {
    setRating(newRating); // Updates the state with the new rating
  };

  return <StarRating initialRating={rating} onRatingChange={handleRatingChange} />;
}

Using State with Direct Setter

This is a more concise approach where the setRating function is passed directly to onRatingChange, eliminating the need for an intermediary function.

import { useState } from 'react';
import { StarRating } from 'react-flexible-star-rating';

function App() {
  const [rating, setRating] = useState(3.5);

  return <StarRating initialRating={rating} onRatingChange={setRating} />;
}

⚙️ Props

📝 Usage Examples

Basic Star Rating

Sample Usage

<StarRating starsLength={5} initialRating={0} onRatingChange={(rating) => console.log(rating)} />

Half-Star Rating

Sample Usage

<StarRating
  starsLength={5}
  initialRating={3.5}
  isHalfRatingEnabled={true}
  onRatingChange={(rating) => console.log(rating)}
/>

Read-only Rating Display

Sample Usage

<StarRating starsLength={5} initialRating={4} isReadOnly={true} />

Custom Styled Rating

Sample Usage

<StarRating starsLength={10} initialRating={5} dimension={50} color="#FF5733" />

Disabled Hover Effects

Sample Usage

<StarRating starsLength={5} initialRating={3} isHoverEnabled={false} />
<StarRating starsLength={5} initialRating={1.5} isHoverEnabled={false} />

🔍 API Details

Rating Validation

• When isHalfRatingEnabled is true, ratings can be in increments of 0.5
• When isHalfRatingEnabled is false, only integer ratings are allowed
• initialRating must be between 0 and starsLength
• The component will throw an error if:
  • initialRating is greater than starsLength
  • initialRating is less than 0
  • starsLength is less than or equal to 0
  • isHoverEnabled is true when isReadOnly is true

Rating Deselection

The component supports rating deselection:

• Click on the same rating twice to cancel/deselect it
• The rating will reset to 0
• The onRatingChange callback will be called with 0

Performance Optimization

• Uses React's useCallback hooks for optimal rendering
• Efficient state updates using React's state management

Browser Compatibility

• Supports all modern browsers (Chrome, Firefox, Safari, Edge)
• Touch events supported for mobile devices