⭐ star-rating-plus

A flexible, lightweight React + Web Component star rating widget with:

• Default yellow hover + selected color
• Support for dynamic per-star colors
• Works with or without Tailwind
• Zero configuration required
• React component and Web Component
• Fully typed, tree‑shakeable, framework‑agnostic

🚀 Installation

npm install star-rating-plus

✨ Basic Usage (React)

⭐ Default — Yellow Rating

If you only specify total, you automatically get:

• total empty stars
• Yellow hover + selection

import { StarRating } from "star-rating-plus";

export default function App() {
  return <StarRating total={5} />;
}

🎨 Dynamic Per‑Star Colors (Multicolor Rating)

You can override default yellow with a color array.

⚠️ The color array must match total.

const colors = [
  "#d90000", // star 1
  "#ff6b6b", // star 2
  "#ffd055", // star 3
  "#b7eb8f", // star 4
  "#237804", // star 5
];

<StarRating total={5} colors={colors} />;

📌 Controlled Component

const [value, setValue] = useState(3);

<StarRating
  total={5}
  value={value}
  onChange={setValue}
/>;

🧩 Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | total | number | ✅ Yes | — | Number of stars | | value | number | ❌ No | 0 | Controlled selected value | | defaultValue | number | ❌ No | 0 | Uncontrolled initial value | | onChange | (v: number) => void | ❌ No | — | Called when user selects a star | | colors | string[] | ❌ No | ["#FFD700", ...] | Must match total. Dynamically colors each star | | size | number | ❌ No | 28 | Star size in px | | className | string | ❌ No | — | Host container styling (including gap-*) |

🌐 Using the Web Component

If you don’t want React, you can use:

<script type="module">
  import "star-rating-plus/dist/web.js";
</script>

<star-rating total="5"></star-rating>

With Multicolor

<star-rating
  total="5"
  hover-colors='["#CD1C18", "#ff6b6b", "#ffd055", "#237804", "#005500"]'
></star-rating>

Spacing (gap)

You can control spacing two ways:

1. If your project uses Tailwind then className="gap-16" works — but only if Tailwind is installed in the host app.
2. For guaranteed spacing across any project, use the gap prop:

// gap as CSS length
<StarRating total={5} gap="2rem" />

// gap as number (interpreted as px)
<StarRating total={5} gap={24} />

---

## 🎯 Using in Angular

```ts
// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from "@angular/core";

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<star-rating total="5"></star-rating>

🎯 Using in Vue

// main.js
import "star-rating-plus/dist/web.js";

<star-rating total="5"></star-rating>

📝 License

MIT © 2025 star-rating-plus team