React Rating Component

A highly customizable, lightweight React rating component with TypeScript support. Perfect for star ratings, reviews, and feedback systems with zero dependencies.

Installation

npm install @aniruddha1806/rating

Features

• ⭐ Customizable star ratings
• 🎨 Fully customizable colors, sizes, and icons
• 🏷️ Support for rating labels and descriptions
• 📱 Responsive design with flexible positioning
• 🔒 Readonly mode for display-only ratings
• 🎯 TypeScript support with full type definitions
• 🪶 Zero dependencies and lightweight
• ♿ Accessible and keyboard-friendly

Quick Start

import { Rating } from '@aniruddha1806/rating';

function App() {
  const handleRatingChange = (value) => {
    console.log('Rating:', value);
  };

  return (
    <Rating
      initialValue={3}
      onChange={handleRatingChange}
    />
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | initialValue | number | 0 | Initial rating value | | maxValue | number | 5 | Maximum number of stars | | size | number | 24 | Size of stars in pixels | | readonly | boolean | false | Make the rating read-only | | activeColor | string | "#FFD700" | Color of active/filled stars | | inactiveColor | string | "#E0E0E0" | Color of inactive/empty stars | | hoverColor | string | "#FFED85" | Color of stars on hover | | emptyIcon | ReactNode | undefined | Custom icon for empty stars | | filledIcon | ReactNode | undefined | Custom icon for filled stars | | halfFilledIcon | ReactNode | undefined | Custom icon for half-filled stars | | onChange | (value: number) => void | undefined | Callback when rating changes | | className | string | "" | Additional CSS class | | style | CSSProperties | {} | Inline styles for container | | showValue | boolean | false | Show numeric rating value | | valuePosition | "left" \\| "right" | "right" | Position of numeric value | | label | string | "" | Label text for the rating | | labelPosition | "top" \\| "bottom" \\| "left" \\| "right" | "top" | Position of label | | gap | number | 4 | Gap between elements in pixels | | ratingLabels | string[] | [] | Array of labels for each rating level | | showRatingLabel | boolean | false | Show descriptive rating label | | ratingLabelPosition | "top" \\| "bottom" | "bottom" | Position of rating label | | ratingLabelStyle | CSSProperties | {} | Styles for rating label |

Examples

Basic Rating

Simple 5-star rating with default styling:

import { Rating } from '@aniruddha1806/rating';

function BasicRating() {
  return (
    <Rating
      initialValue={3}
      onChange={(value) => console.log(value)}
    />
  );
}

Custom Colors and Size

Customize the appearance with different colors and sizes:

import { Rating } from '@aniruddha1806/rating';

function CustomRating() {
  return (
    <Rating
      initialValue={4}
      size={32}
      activeColor="#FF6B6B"
      inactiveColor="#DDD"
      hoverColor="#FF8E8E"
      onChange={(value) => console.log(value)}
    />
  );
}

With Rating Labels

Add descriptive labels for each rating level:

import { Rating } from '@aniruddha1806/rating';

function LabeledRating() {
  const ratingLabels = [
    "Terrible",
    "Poor", 
    "Average",
    "Good",
    "Excellent"
  ];

  return (
    <Rating
      initialValue={3}
      ratingLabels={ratingLabels}
      showRatingLabel={true}
      ratingLabelPosition="bottom"
      onChange={(value) => console.log(value)}
    />
  );
}

Custom Icons

Use custom icons instead of default stars:

import { Rating } from '@aniruddha1806/rating';
import { Heart, HeartOff } from 'lucide-react';

function CustomIconRating() {
  return (
    <Rating
      initialValue={3}
      maxValue={5}
      emptyIcon={<HeartOff size={24} />}
      filledIcon={<Heart size={24} />}
      activeColor="#E91E63"
      inactiveColor="#CCCCCC"
      onChange={(value) => console.log(value)}
    />
  );
}

Readonly Display

Show ratings without allowing interaction:

import { Rating } from '@aniruddha1806/rating';

function ReadonlyRating() {
  return (
    <Rating
      initialValue={4.5}
      
      readonly={true}
      showValue={true}
      valuePosition="right"
    />
  );
}

With Label and Value

Display rating with label and numeric value:

import { Rating } from '@aniruddha1806/rating';

function LabeledValueRating() {
  return (
    <Rating
      initialValue={4}
      label="Rate this product:"
      labelPosition="top"
      showValue={true}
      valuePosition="right"
      onChange={(value) => console.log(value)}
    />
  );
}

Product Review Style

Complete rating component for product reviews:

import { Rating } from '@aniruddha1806/rating';

function ProductReview() {
  const ratingLabels = [
    "Poor",
    "Fair", 
    "Good",
    "Very Good",
    "Excellent"
  ];

  return (
    <div className="product-review">
      <Rating
        initialValue={0}

        size={28}
        activeColor="#FFA500"
        hoverColor="#FFD700"
        label="Rate your experience:"
        labelPosition="top"
        showValue={true}
        valuePosition="right"
        ratingLabels={ratingLabels}
        showRatingLabel={true}
        ratingLabelPosition="bottom"
        gap={6}
        onChange={(value) => console.log('Review rating:', value)}
        style={{ marginBottom: '20px' }}
      />
    </div>
  );
}

TypeScript Usage

The component is fully typed and provides excellent TypeScript support:

import { Rating, RatingProps } from '@aniruddha1806/rating';

interface ReviewFormProps {
  onSubmit: (rating: number) => void;
}

const ReviewForm: React.FC<ReviewFormProps> = ({ onSubmit }) => {
  const [rating, setRating] = useState<number>(0);

  const handleRatingChange = (value: number): void => {
    setRating(value);
    onSubmit(value);
  };

  const ratingProps: RatingProps = {
    initialValue: rating,
    maxValue: 5,
    onChange: handleRatingChange,
    activeColor: "#FFD700",
    size: 24
  };

  return <Rating {...ratingProps} />;
};

Styling

The component uses inline styles for maximum compatibility and doesn't require any CSS imports. You can customize the appearance using the provided props or by applying custom styles through the className and style props.