npm install star-rating-xv1.0.0TypeScriptZero deps

star-rating-x

A fully-featured, accessible, customisable React rating component. Themes · Shapes · Animations · Half-star · RTL.

Click a star · keyboard ← → also works

01 · Getting Started

Quick Start

npm install star-rating-x

import { StarRating } from "star-rating-x";
import "star-rating-x/styles.css";

function App() {
  const [rating, setRating] = useState(0);
  return <StarRating value={rating} onChange={setRating} />;
}

02 · Theming

9 Built-in Themes

gold

fire

ocean

neon

rose

mono

violet

sunset

mint

<StarRating theme="fire" />
<StarRating theme="neon" />
<StarRating theme="ocean" />

// or override colours directly:
<StarRating filledColor="#FF6B6B" emptyColor="#FFE0E0" strokeColor="#CC0000" />

03 · Shapes

8 Icon Shapes

star

heart

circle

diamond

thumb

flag

lightning

flower

<StarRating shape="heart"     theme="rose"  />
<StarRating shape="thumb"     theme="ocean" />
<StarRating shape="lightning" theme="neon"  />
<StarRating shape="diamond"   theme="violet" />

04 · Animations

Click Animations

bounce

pulse

wiggle

pop

<StarRating animation="bounce" />  {/* default */}
<StarRating animation="wiggle" />
<StarRating animation="pop"    />
<StarRating animation="pulse"  />
<StarRating animation="none"   />  {/* disable */}

05 · Precision

Half-Star Support

precision={0.5}

Hover anywhere on a star to get half or full — hover left half for 0.5, right half for 1.

1.5

2.5

3.5

4.5

<StarRating
  precision={0.5}
  defaultValue={3.5}
  theme="gold"
/>

06 · Sizing

Any Size

size prop

Pass any number (px) or CSS string.

16px

24px

32px

44px

56px

<StarRating size={16} />
<StarRating size={32} />  {/* default */}
<StarRating size={56} />

07 · Display

Read-only & Show Value

readOnly + showValue

Perfect for displaying user-submitted ratings on product pages.

<StarRating
  value={4.5}
  precision={0.5}
  readOnly
  showValue
  theme="gold"
/>

08 · State

Controlled Component

value + onChange

Full control over the value from outside the component.

Selected: 3

const [rating, setRating] = useState(3);

<StarRating
  value={rating}
  onChange={setRating}
  theme="ocean"
  animation="pop"
/>

09 · Hook

useRating Hook

External state management

Manage the rating value outside the component — useful for forms.

value: 2

import { StarRating, useRating } from "star-rating-x";

function ProductRating() {
  const { value, handlers, reset } = useRating({
    initialValue: 3,
  });

  return (
    <>
      <StarRating value={value} {...handlers} />
      <button onClick={reset}>Reset</button>
    </>
  );
}

10 · UX

Custom Tooltips

tooltips prop

Provide a label for each star — shown on hover and used for accessibility.

<StarRating
  tooltips={[
    "Terrible 😡",
    "Bad 😕",
    "Ok 😐",
    "Good 😊",
    "Amazing! 🤩",
  ]}
/>

11 · i18n

RTL Support

direction="rtl"

Full right-to-left layout — perfect for Arabic, Hebrew, and other RTL languages.

تقييم المنتج

// Arabic / Hebrew RTL layout
<StarRating
  direction="rtl"
  defaultValue={4}
  theme="gold"
/>

12 · States

Disabled State

Normal

Disabled

<StarRating disabled defaultValue={3} />

13 · TypeScript

Full Type Safety

import type {
  StarRatingProps,
  StarShape,      // "star"|"heart"|"circle"|"diamond"|"thumb"|"flag"|"lightning"|"flower"
  ThemeName,      // "gold"|"fire"|"ocean"|"neon"|"rose"|"mono"|"violet"|"sunset"|"mint"
  AnimationType,  // "bounce"|"pulse"|"wiggle"|"pop"|"none"
  UseRatingResult,
} from "star-rating-x";

// All props are typed:
const props: StarRatingProps = {
  value: 4,
  count: 5,
  precision: 0.5,
  shape: "heart",
  theme: "rose",
  animation: "wiggle",
  onChange: (v: number) => console.log(v),
};