Ratti

React Star Rating - Zero dependency, a highly-configurable, accessible rating component for React applications with TypeScript support.

🌐 Live Demo

Features

• Flexible Rating System: Support stars with fractional ratings
• Multiple Variants: Default, Circle, and Square background styles
• Custom Colors: Built-in color schemes or custom color arrays
• Accessibility: Full keyboard navigation and ARIA support
• Responsive: Works seamlessly across all device sizes
• Precision Control: Configurable rating precision (0.1, 0.5, 1.0, etc.)
• Interactive States: Hover, focus, and active states with smooth transitions
• Customizable: Custom SVG icons, sizes, and styling
• Zero Dependencies: Pure React component with no external dependencies

Installation

npm install ratti
# or
yarn add ratti
# or
pnpm add ratti

Basic Usage

Simple Star Rating

import { RateStar } from 'ratti';

<RateStar maxRating={5} defaultValue={3} />

Controlled Component

import { RateStar } from 'ratti';
import { useState } from 'react';

function RatingComponent() {
  const [rating, setRating] = useState(2.5);

  return (
    <RateStar
      maxRating={5}
      value={rating}
      onChange={setRating}
      precision={0.5}
    />
  );
}

Fractional Ratings

<RateStar
  maxRating={5}
  defaultValue={3.5}
  precision={0.5} // Allows half-star ratings
/>

Variants

Default Variant

The classic star rating with direct color application.

<RateStar
  maxRating={5}
  defaultValue={4}
  variant="default"
  activeColorsEnabled
/>

Circle Variant

Stars displayed on circular backgrounds.

<RateStar
  maxRating={5}
  defaultValue={3}
  variant="circle"
  activeColorsEnabled
/>

Square Variant

Stars displayed on square backgrounds.

<RateStar
  maxRating={5}
  defaultValue={2}
  variant="square"
  activeColorsEnabled
/>

Color Customization

Built-in Color Schemes

<RateStar
  maxRating={5}
  defaultValue={4}
  activeColorsEnabled
  // Uses default color progression: red → orange → yellow → green
/>

Custom Colors

<RateStar
  maxRating={7}
  defaultValue={5}
  activeColorsEnabled
  customActiveColors={[
    "#d90429", // Red
    "#f77f00", // Orange
    "#fcbf49", // Yellow
    "#eae2b7", // Light yellow
    "#003049", // Dark blue
    "#d62828", // Dark red
    "#f77f00"  // Orange
  ]}
/>

Event Handlers

<RateStar
  maxRating={5}
  defaultValue={0}
  onChange={(rating) => console.log('Rating changed:', rating)}
  onHoverChange={(hoverRating) => console.log('Hover rating:', hoverRating)}
  onBlur={(event) => console.log('Component lost focus')}
/>

API Reference

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | maxRating | number | 5 | Maximum number of stars (1-15) | | defaultValue | number | 0 | Initial rating value | | value | number | - | Controlled rating value | | onChange | (rating: number) => void | - | Callback when rating changes | | onHoverChange | (hoverRating: number) => void | - | Callback when hover rating changes | | onBlur | (event: React.FocusEvent) => void | - | Callback when component loses focus | | disabled | boolean | false | Whether the component is disabled | | readOnly | boolean | false | Whether the component is read-only | | precision | number | 1 | Rating precision (0.1, 0.5, 1.0, etc.) | | activeColorsEnabled | boolean | false | Enable color progression | | customActiveColors | string[] | - | Custom color array for rating levels | | variant | 'default' \| 'circle' \| 'square' | 'default' | Visual variant | | svgPathD | string | - | Custom SVG path data | | className | string | - | Additional CSS class name | | size | number \| string | - | Star size (px or CSS unit) |

Types

export type StarRatingVariant = "default" | "circle" | "square";

export interface StarRatingProps {
  maxRating?: number;
  defaultValue?: number;
  value?: number;
  onChange?: (rating: number) => void;
  onHoverChange?: (hoverRating: number) => void;
  onBlur?: (event: React.FocusEvent<HTMLDivElement>) => void;
  disabled?: boolean;
  readOnly?: boolean;
  precision?: number;
  activeColorsEnabled?: boolean;
  customActiveColors?: string[];
  variant?: StarRatingVariant;
  svgPathD?: string;
  className?: string;
  size?: number | string;
}

Accessibility

Ratti is built with accessibility in mind:

• ARIA Support: Proper role, aria-valuemin, aria-valuemax, aria-valuenow, and aria-valuetext attributes
• Keyboard Navigation: Full keyboard support with arrow keys, Home, End, Enter, and Space
• Focus Management: Visible focus indicators and proper focus handling
• Screen Reader Support: Descriptive labels and state announcements

Keyboard Controls

• Arrow Keys: Navigate between stars
• Home: Jump to first star (0 rating)
• End: Jump to last star (max rating)
• Enter/Space: Select current rating
• Tab: Navigate to/from component

Styling

CSS Custom Properties

The component uses CSS custom properties for easy theming:

.star-rating {
  --star-size: 24px;
  --star-gap: 4px;
  --star-color: #f59e0b;
  --star-hover-color: #fbbf24;
  --star-selected-color: #f59e0b;
  --star-disabled-color: #94a3b8;
  --star-transition: all 0.2s ease;
  --star-hover-scale: 1.1;
  --star-active-scale: 0.95;
}

Variant-Specific Properties

For circle and square variants, additional properties are available:

.star-rating {
  /* Circle variant */
  --star-circle-radius: 50%;
  
  /* Square variant */
  --star-square-radius: 4px;
  
  /* Background properties for circle/square variants */
  --star-bg-default: #dddddd;
  --star-bg-selected: var(--star-selected-color);
  --star-active-bg-color: var(--star-selected-color);
  --star-icon-on-bg: #ffffff;
}

Custom Styling

<RateStar
  maxRating={5}
  defaultValue={3}
  className="my-custom-rating"
/>

.my-custom-rating {
  --star-color: #3b82f6;
  --star-hover-color: #60a5fa;
  --star-selected-color: #1d4ed8;
}

/* Custom circle variant */
.my-custom-rating.variant-circle {
  --star-circle-radius: 25%;
  --star-bg-default: #e5e7eb;
  --star-bg-selected: #3b82f6;
}

/* Custom square variant */
.my-custom-rating.variant-square {
  --star-square-radius: 8px;
  --star-bg-default: #f3f4f6;
  --star-bg-selected: #10b981;
}