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.

🎮 Live Demos 🚀

See all interactive demos and usage examples in action:

🎯 Interactive Demo Gallery – Explore All Features & Examples

✨ Basic Star Rating – Simple & clean star rating
🌗 Half-Star Rating – Supports half-star selection
🔴 Custom Styled Rating (Red) – Red-themed stars
🟢 Custom Styled Rating (Green) – Green-themed stars
🔵 Custom Styled Rating (Blue) – Blue-themed stars
⭐ Single Large Star – A big bold rating star
🔒 Read-only Rating – Non-editable rating display
🚫 Disabled Hover Effects – No hover animations

🚀 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
  • Final Bundle Size: 15.7 kB (compressed .tgz file size)
  • Unpacked Size: 70.2 kB (size after npm install)

📦 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 to Handle Rating Changes

This example demonstrates how to handle rating changes using a custom callback function. The initial rating value starts at 0, and the rating is logged to the console each time the user clicks on a star. 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}`);
  };

  /*
    ⚠️ Note
    
    To enable half-star ratings with an initial value of 0,
    set the `isHalfRatingEnabled` prop to `true`.

    Example usages:
      `<StarRating isHalfRatingEnabled={true} />`
      `<StarRating initialRating={0} isHalfRatingEnabled={true} />`
  */
  return <StarRating onRatingChange={handleRatingChange} />;
}

---

Using useState Hook with a Handler Function

This example demonstrates how to manage the rating value using the useState hook while also logging the rating changes to the console.

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

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

  const handleRatingChange = (newRating: number) => {
    console.log(`New rating: ${newRating}`);
    setRating(newRating);
  };

  /* 
    ⚠️ Important Note: Proper Usage of `initialRating` 

      ❌ Incorrect (Avoid this):  
        `<StarRating initialRating={rating} />`  
        - Binding `initialRating` to state can cause half-ratings to behave like integers.  

      ✅ Correct (Use one of these approaches):  
        - Static value: `<StarRating initialRating={3.5} />`  

        - Defined variable:  
          `const ratingValue = 3.5;`
          ...
          `<StarRating initialRating={ratingValue} />`  

      This ensures proper half-rating functionality of the component.
  */
  return <StarRating initialRating={ratingValue} onRatingChange={handleRatingChange} />;
}

---

Using setState Function Directly

This example demonstrates how to manage the rating value using the useState hook without needing a separate handler function. The state is updated directly when the user selects a new rating.

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

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

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

Next.js Usage

⚠️ Important Note for Next.js Users

When using this component in Next.js applications, you must add the "use client" directive at the top of your component file. This is because the star rating component uses React hooks (useState, useCallback), which can only be used in client-side components.

Sample Usage in Next.js

'use client'; // ⚠️ Required: do not forget this line

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

export default function RatingComponent() {
  const initialRatingValue = 2;
  const [rating, setRating] = useState(initialRatingValue);

  return (
    <div>
      <h2>Product Rating</h2>
      <StarRating initialRating={initialRatingValue} onRatingChange={setRating} />
      <p>Current Rating: {rating}</p>
    </div>
  );
}

⚙️ Props

Prop	Type	Default	Description
starsLength	number	5	Number of stars to display
isHalfRatingEnabled	boolean	false	Enable half-star ratings
isHoverEnabled	boolean	true	Enable hover effects
isReadOnly	boolean	false	Make the rating read-only
initialRating	number	0	Initial rating value
dimension	number	30	Size (width & height) of stars in rem
color	string	"#FFD700"	Star color in HEX format
onRatingChange	(rating: number) => void	undefined	Accepts setState or custom callback function to handle rating changes

---

📝 Usage Examples

Basic Star Rating

⚡ Interactive Demo

---

---

Sample Usage

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

Half-Star Rating

⚡ Interactive Demo

---

---

Sample Usage

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

Read-only Rating Display

⚡ Interactive Demo

---

---

Sample Usage

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

Custom Styled Rating

⚡ Interactive Demo

---

---

Sample Usage

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

Disabled Hover Effects

⚡ Interactive Demo

---

---

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

🔮 TODO Features

Here are some exciting features planned for future releases:

• 🌐 Live Demo - An interactive demo website to showcase component features ✅
• ⌨️ Keyboard Navigation
  • Arrow keys for rating selection
  • Space/Enter for rating confirmation
  • Escape key for rating reset
• 🗣️ Voice Control
  • Voice commands for setting specific ratings
  • Natural language support for rating control
  • Voice feedback for current rating state
  • Voice-activated rating reset
• ♿ Screen Reader Accessibility
  • Improved ARIA labels and descriptions
  • Better announcement of rating changes
  • Enhanced focus management

📧 Contact

For questions or suggestions, email me at: suhatanriverdi.dev@gmail.com

Your support means a lot to me to continue the development of open-source projects like this.

Created by Süha Tanrıverdi, 2025