React Rating Button

React rating button with interactive star ratings and hover effects. Lucide icons with keyboard navigation and form integration using TypeScript and shadcn/ui.

React

Lucide React

Tailwind CSS

Building rating interactions?

Join our Discord community for help from other developers.

Rating systems are everywhere—product reviews, content feedback, skill assessments. But most are just static star icons that highlight on click. Basic. Uninspiring. No hover previews or smooth transitions. Meanwhile, users expect rich feedback that guides their selection and confirms their choice. This React component gives you interactive star rating buttons with hover previews, smooth animations, and comprehensive accessibility that make every rating feel intentional and satisfying.

Loading component...

'use client';import { useControllableState } from '@radix-ui/react-use-controllable-state';import { type LucideProps, StarIcon } from 'lucide-react';import type { KeyboardEvent, MouseEvent, ReactElement, ReactNode } from 'react';import {  Children,  cloneElement,  createContext,  useCallback,  useContext,  useEffect,  useRef,  useState,} from 'react';import { cn } from '@/lib/utils';type RatingContextValue = {  value: number;  readOnly: boolean;  hoverValue: number | null;  focusedStar: number | null;  handleValueChange: (    event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLButtonElement>,    value: number  ) => void;  handleKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => void;  setHoverValue: (value: number | null) => void;  setFocusedStar: (value: number | null) => void;};const RatingContext = createContext<RatingContextValue | null>(null);const useRating = () => {  const context = useContext(RatingContext);  if (!context) {    throw new Error('useRating must be used within a Rating component');  }  return context;};export type RatingButtonProps = LucideProps & {  index?: number;  icon?: ReactElement<LucideProps>;};export const RatingButton = ({  index: providedIndex,  size = 20,  className,  icon = <StarIcon />,}: RatingButtonProps) => {  const {    value,    readOnly,    hoverValue,    focusedStar,    handleValueChange,    handleKeyDown,    setHoverValue,    setFocusedStar,  } = useRating();  const index = providedIndex ?? 0;  const isActive = index < (hoverValue ?? focusedStar ?? value ?? 0);  let tabIndex = -1;  if (!readOnly) {    tabIndex = value === index + 1 ? 0 : -1;  }  const handleClick = useCallback(    (event: MouseEvent<HTMLButtonElement>) => {      handleValueChange(event, index + 1);    },    [handleValueChange, index]  );  const handleMouseEnter = useCallback(() => {    if (!readOnly) {      setHoverValue(index + 1);    }  }, [readOnly, setHoverValue, index]);  const handleFocus = useCallback(() => {    setFocusedStar(index + 1);  }, [setFocusedStar, index]);  const handleBlur = useCallback(() => {    setFocusedStar(null);  }, [setFocusedStar]);  return (    <button      className={cn(        'rounded-full focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',        'p-0.5',        readOnly && 'cursor-default',        className      )}      disabled={readOnly}      onBlur={handleBlur}      onClick={handleClick}      onFocus={handleFocus}      onKeyDown={handleKeyDown}      onMouseEnter={handleMouseEnter}      tabIndex={tabIndex}      type="button"    >      {cloneElement(icon, {        size,        className: cn(          'transition-colors duration-200',          isActive && 'fill-current',          !readOnly && 'cursor-pointer'        ),        'aria-hidden': 'true',      })}    </button>  );};export type RatingProps = {  defaultValue?: number;  value?: number;  onChange?: (    event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLButtonElement>,    value: number  ) => void;  onValueChange?: (value: number) => void;  readOnly?: boolean;  className?: string;  children?: ReactNode;};export const Rating = ({  value: controlledValue,  onValueChange: controlledOnValueChange,  defaultValue = 0,  onChange,  readOnly = false,  className,  children,  ...props}: RatingProps) => {  const [hoverValue, setHoverValue] = useState<number | null>(null);  const [focusedStar, setFocusedStar] = useState<number | null>(null);  const containerRef = useRef<HTMLDivElement>(null);  const [value, onValueChange] = useControllableState({    defaultProp: defaultValue,    prop: controlledValue,    onChange: controlledOnValueChange,  });  const handleValueChange = useCallback(    (      event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLButtonElement>,      newValue: number    ) => {      if (!readOnly) {        onChange?.(event, newValue);        onValueChange?.(newValue);      }    },    [readOnly, onChange, onValueChange]  );  const handleKeyDown = useCallback(    (event: KeyboardEvent<HTMLButtonElement>) => {      if (readOnly) {        return;      }      const total = Children.count(children);      let newValue = focusedStar !== null ? focusedStar : (value ?? 0);      switch (event.key) {        case 'ArrowRight':          if (event.shiftKey || event.metaKey) {            newValue = total;          } else {            newValue = Math.min(total, newValue + 1);          }          break;        case 'ArrowLeft':          if (event.shiftKey || event.metaKey) {            newValue = 1;          } else {            newValue = Math.max(1, newValue - 1);          }          break;        default:          return;      }      event.preventDefault();      setFocusedStar(newValue);      handleValueChange(event, newValue);    },    [focusedStar, value, children, readOnly, handleValueChange]  );  useEffect(() => {    if (focusedStar !== null && containerRef.current) {      const buttons = containerRef.current.querySelectorAll('button');      buttons[focusedStar - 1]?.focus();    }  }, [focusedStar]);  const contextValue: RatingContextValue = {    value: value ?? 0,    readOnly,    hoverValue,    focusedStar,    handleValueChange,    handleKeyDown,    setHoverValue,    setFocusedStar,  };  return (    <RatingContext.Provider value={contextValue}>      <div        aria-label="Rating"        className={cn('inline-flex items-center gap-0.5', className)}        onMouseLeave={() => setHoverValue(null)}        ref={containerRef}        role="radiogroup"        {...props}      >        {Children.map(children, (child, index) => {          if (!child) {            return null;          }          return cloneElement(child as ReactElement<RatingButtonProps>, {            index,          });        })}      </div>    </RatingContext.Provider>  );};

Built for React applications with TypeScript and Next.js. Uses Lucide icons for crisp star rendering at any size. The component doesn't just track ratings—it provides hover previews, keyboard navigation, and smooth transitions between states. Form integration works seamlessly with React Hook Form and other libraries. Perfect for shadcn/ui design systems with consistent styling patterns.

Why most rating components feel disconnected

Developers throw five star icons in a row and add click handlers. Maybe they change the fill color if they're being thorough. The problem? Users can't preview their selection before committing. There's no visual feedback during interaction. Keyboard users get ignored entirely. It's functional but not user-friendly.

This component provides hover previews that show exactly what rating you're about to select. Smooth transitions between states create visual continuity. Keyboard navigation with arrow keys feels natural and accessible. The compound component pattern gives you full control over styling while handling all the complex interaction states automatically.

Built with proper ARIA attributes and screen reader support, so all users can provide meaningful feedback regardless of how they interact with your interface.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/rating.json

npx shadcn@latest add https://www.shadcn.io/registry/rating.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/rating.json

bunx shadcn@latest add https://www.shadcn.io/registry/rating.json

Examples

Style Variations

Different colors and sizes for various UI contexts:

Loading component...

'use client';import { useControllableState } from '@radix-ui/react-use-controllable-state';import { type LucideProps, StarIcon } from 'lucide-react';import type { KeyboardEvent, MouseEvent, ReactElement, ReactNode } from 'react';import {  Children,  cloneElement,  createContext,  useCallback,  useContext,  useEffect,  useRef,  useState,} from 'react';import { cn } from '@/lib/utils';type RatingContextValue = {  value: number;  readOnly: boolean;  hoverValue: number | null;  focusedStar: number | null;  handleValueChange: (    event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLButtonElement>,    value: number  ) => void;  handleKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => void;  setHoverValue: (value: number | null) => void;  setFocusedStar: (value: number | null) => void;};const RatingContext = createContext<RatingContextValue | null>(null);const useRating = () => {  const context = useContext(RatingContext);  if (!context) {    throw new Error('useRating must be used within a Rating component');  }  return context;};export type RatingButtonProps = LucideProps & {  index?: number;  icon?: ReactElement<LucideProps>;};export const RatingButton = ({  index: providedIndex,  size = 20,  className,  icon = <StarIcon />,}: RatingButtonProps) => {  const {    value,    readOnly,    hoverValue,    focusedStar,    handleValueChange,    handleKeyDown,    setHoverValue,    setFocusedStar,  } = useRating();  const index = providedIndex ?? 0;  const isActive = index < (hoverValue ?? focusedStar ?? value ?? 0);  let tabIndex = -1;  if (!readOnly) {    tabIndex = value === index + 1 ? 0 : -1;  }  const handleClick = useCallback(    (event: MouseEvent<HTMLButtonElement>) => {      handleValueChange(event, index + 1);    },    [handleValueChange, index]  );  const handleMouseEnter = useCallback(() => {    if (!readOnly) {      setHoverValue(index + 1);    }  }, [readOnly, setHoverValue, index]);  const handleFocus = useCallback(() => {    setFocusedStar(index + 1);  }, [setFocusedStar, index]);  const handleBlur = useCallback(() => {    setFocusedStar(null);  }, [setFocusedStar]);  return (    <button      className={cn(        'rounded-full focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',        'p-0.5',        readOnly && 'cursor-default',        className      )}      disabled={readOnly}      onBlur={handleBlur}      onClick={handleClick}      onFocus={handleFocus}      onKeyDown={handleKeyDown}      onMouseEnter={handleMouseEnter}      tabIndex={tabIndex}      type="button"    >      {cloneElement(icon, {        size,        className: cn(          'transition-colors duration-200',          isActive && 'fill-current',          !readOnly && 'cursor-pointer'        ),        'aria-hidden': 'true',      })}    </button>  );};export type RatingProps = {  defaultValue?: number;  value?: number;  onChange?: (    event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLButtonElement>,    value: number  ) => void;  onValueChange?: (value: number) => void;  readOnly?: boolean;  className?: string;  children?: ReactNode;};export const Rating = ({  value: controlledValue,  onValueChange: controlledOnValueChange,  defaultValue = 0,  onChange,  readOnly = false,  className,  children,  ...props}: RatingProps) => {  const [hoverValue, setHoverValue] = useState<number | null>(null);  const [focusedStar, setFocusedStar] = useState<number | null>(null);  const containerRef = useRef<HTMLDivElement>(null);  const [value, onValueChange] = useControllableState({    defaultProp: defaultValue,    prop: controlledValue,    onChange: controlledOnValueChange,  });  const handleValueChange = useCallback(    (      event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLButtonElement>,      newValue: number    ) => {      if (!readOnly) {        onChange?.(event, newValue);        onValueChange?.(newValue);      }    },    [readOnly, onChange, onValueChange]  );  const handleKeyDown = useCallback(    (event: KeyboardEvent<HTMLButtonElement>) => {      if (readOnly) {        return;      }      const total = Children.count(children);      let newValue = focusedStar !== null ? focusedStar : (value ?? 0);      switch (event.key) {        case 'ArrowRight':          if (event.shiftKey || event.metaKey) {            newValue = total;          } else {            newValue = Math.min(total, newValue + 1);          }          break;        case 'ArrowLeft':          if (event.shiftKey || event.metaKey) {            newValue = 1;          } else {            newValue = Math.max(1, newValue - 1);          }          break;        default:          return;      }      event.preventDefault();      setFocusedStar(newValue);      handleValueChange(event, newValue);    },    [focusedStar, value, children, readOnly, handleValueChange]  );  useEffect(() => {    if (focusedStar !== null && containerRef.current) {      const buttons = containerRef.current.querySelectorAll('button');      buttons[focusedStar - 1]?.focus();    }  }, [focusedStar]);  const contextValue: RatingContextValue = {    value: value ?? 0,    readOnly,    hoverValue,    focusedStar,    handleValueChange,    handleKeyDown,    setHoverValue,    setFocusedStar,  };  return (    <RatingContext.Provider value={contextValue}>      <div        aria-label="Rating"        className={cn('inline-flex items-center gap-0.5', className)}        onMouseLeave={() => setHoverValue(null)}        ref={containerRef}        role="radiogroup"        {...props}      >        {Children.map(children, (child, index) => {          if (!child) {            return null;          }          return cloneElement(child as ReactElement<RatingButtonProps>, {            index,          });        })}      </div>    </RatingContext.Provider>  );};

Interactive States

Controlled, read-only, and interactive rating examples:

Loading component...

'use client';import { useControllableState } from '@radix-ui/react-use-controllable-state';import { type LucideProps, StarIcon } from 'lucide-react';import type { KeyboardEvent, MouseEvent, ReactElement, ReactNode } from 'react';import {  Children,  cloneElement,  createContext,  useCallback,  useContext,  useEffect,  useRef,  useState,} from 'react';import { cn } from '@/lib/utils';type RatingContextValue = {  value: number;  readOnly: boolean;  hoverValue: number | null;  focusedStar: number | null;  handleValueChange: (    event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLButtonElement>,    value: number  ) => void;  handleKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => void;  setHoverValue: (value: number | null) => void;  setFocusedStar: (value: number | null) => void;};const RatingContext = createContext<RatingContextValue | null>(null);const useRating = () => {  const context = useContext(RatingContext);  if (!context) {    throw new Error('useRating must be used within a Rating component');  }  return context;};export type RatingButtonProps = LucideProps & {  index?: number;  icon?: ReactElement<LucideProps>;};export const RatingButton = ({  index: providedIndex,  size = 20,  className,  icon = <StarIcon />,}: RatingButtonProps) => {  const {    value,    readOnly,    hoverValue,    focusedStar,    handleValueChange,    handleKeyDown,    setHoverValue,    setFocusedStar,  } = useRating();  const index = providedIndex ?? 0;  const isActive = index < (hoverValue ?? focusedStar ?? value ?? 0);  let tabIndex = -1;  if (!readOnly) {    tabIndex = value === index + 1 ? 0 : -1;  }  const handleClick = useCallback(    (event: MouseEvent<HTMLButtonElement>) => {      handleValueChange(event, index + 1);    },    [handleValueChange, index]  );  const handleMouseEnter = useCallback(() => {    if (!readOnly) {      setHoverValue(index + 1);    }  }, [readOnly, setHoverValue, index]);  const handleFocus = useCallback(() => {    setFocusedStar(index + 1);  }, [setFocusedStar, index]);  const handleBlur = useCallback(() => {    setFocusedStar(null);  }, [setFocusedStar]);  return (    <button      className={cn(        'rounded-full focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',        'p-0.5',        readOnly && 'cursor-default',        className      )}      disabled={readOnly}      onBlur={handleBlur}      onClick={handleClick}      onFocus={handleFocus}      onKeyDown={handleKeyDown}      onMouseEnter={handleMouseEnter}      tabIndex={tabIndex}      type="button"    >      {cloneElement(icon, {        size,        className: cn(          'transition-colors duration-200',          isActive && 'fill-current',          !readOnly && 'cursor-pointer'        ),        'aria-hidden': 'true',      })}    </button>  );};export type RatingProps = {  defaultValue?: number;  value?: number;  onChange?: (    event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLButtonElement>,    value: number  ) => void;  onValueChange?: (value: number) => void;  readOnly?: boolean;  className?: string;  children?: ReactNode;};export const Rating = ({  value: controlledValue,  onValueChange: controlledOnValueChange,  defaultValue = 0,  onChange,  readOnly = false,  className,  children,  ...props}: RatingProps) => {  const [hoverValue, setHoverValue] = useState<number | null>(null);  const [focusedStar, setFocusedStar] = useState<number | null>(null);  const containerRef = useRef<HTMLDivElement>(null);  const [value, onValueChange] = useControllableState({    defaultProp: defaultValue,    prop: controlledValue,    onChange: controlledOnValueChange,  });  const handleValueChange = useCallback(    (      event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLButtonElement>,      newValue: number    ) => {      if (!readOnly) {        onChange?.(event, newValue);        onValueChange?.(newValue);      }    },    [readOnly, onChange, onValueChange]  );  const handleKeyDown = useCallback(    (event: KeyboardEvent<HTMLButtonElement>) => {      if (readOnly) {        return;      }      const total = Children.count(children);      let newValue = focusedStar !== null ? focusedStar : (value ?? 0);      switch (event.key) {        case 'ArrowRight':          if (event.shiftKey || event.metaKey) {            newValue = total;          } else {            newValue = Math.min(total, newValue + 1);          }          break;        case 'ArrowLeft':          if (event.shiftKey || event.metaKey) {            newValue = 1;          } else {            newValue = Math.max(1, newValue - 1);          }          break;        default:          return;      }      event.preventDefault();      setFocusedStar(newValue);      handleValueChange(event, newValue);    },    [focusedStar, value, children, readOnly, handleValueChange]  );  useEffect(() => {    if (focusedStar !== null && containerRef.current) {      const buttons = containerRef.current.querySelectorAll('button');      buttons[focusedStar - 1]?.focus();    }  }, [focusedStar]);  const contextValue: RatingContextValue = {    value: value ?? 0,    readOnly,    hoverValue,    focusedStar,    handleValueChange,    handleKeyDown,    setHoverValue,    setFocusedStar,  };  return (    <RatingContext.Provider value={contextValue}>      <div        aria-label="Rating"        className={cn('inline-flex items-center gap-0.5', className)}        onMouseLeave={() => setHoverValue(null)}        ref={containerRef}        role="radiogroup"        {...props}      >        {Children.map(children, (child, index) => {          if (!child) {            return null;          }          return cloneElement(child as ReactElement<RatingButtonProps>, {            index,          });        })}      </div>    </RatingContext.Provider>  );};

Features

Interactive star buttons with click and hover rating selection using JavaScript events
Hover preview states showing rating selection before confirmation
Keyboard navigation with arrow key support and accessible focus management
Form integration with hidden input fields for seamless form library compatibility
Customizable appearance with star count, size, colors, and icons using Tailwind CSS
Read-only mode for display-only ratings with proper ARIA attributes
TypeScript definitions with complete interface definitions and prop validation
Accessible design with comprehensive ARIA support and screen reader compatibility
Compound component pattern for flexible composition and styling control
Lucide icon integration for crisp, scalable star rendering at any size

Use Cases

This free open source React component works perfectly for:

Product reviews - Customer feedback and rating collection systems built with Next.js
Content rating - Article, video, and media quality assessments using TypeScript
Skill assessment - User proficiency and experience level indicators
Satisfaction surveys - Service quality and experience feedback forms
Course evaluation - Educational content and instructor rating systems
Restaurant reviews - Food and service quality rating interfaces
App store ratings - Software and mobile app user feedback collection
Performance reviews - Employee and team assessment rating tools

API Reference

Rating

The container component providing context for all rating functionality.

Prop	Type	Default	Description
`defaultValue`	`number`	`0`	Initial rating value for uncontrolled mode
`value`	`number`	-	Current rating value for controlled mode
`onValueChange`	`(value: number) => void`	-	Callback when rating value changes
`max`	`number`	`5`	Maximum rating value (number of stars)
`readOnly`	`boolean`	`false`	Disables interaction and shows display-only mode
`disabled`	`boolean`	`false`	Disables all rating interactions
`name`	`string`	-	Form input name for form integration
`required`	`boolean`	`false`	Makes rating selection required for forms
`className`	`string`	-	Additional CSS classes for container

RatingButton

Individual star button component for rating selection.

Prop	Type	Default	Description
`size`	`number`	`24`	Icon size in pixels for consistent scaling
`className`	`string`	-	Additional CSS classes for star styling
`icon`	`React.ElementType`	`Star`	Custom icon component (must accept size prop)
`filledIcon`	`React.ElementType`	`Star`	Icon for filled/selected state
`emptyIcon`	`React.ElementType`	`Star`	Icon for empty/unselected state
`...props`	`ButtonHTMLAttributes`	-	All native button props supported

Rating States

State	Visual	Interaction	Use Case
`empty`	Outlined stars	Clickable, hoverable	Unrated content
`filled`	Solid stars	Clickable, hoverable	Current rating display
`hover`	Preview fill	Temporary highlight	Selection preview
`readOnly`	Static display	No interaction	Display existing ratings
`disabled`	Muted appearance	No interaction	Unavailable rating

Key	Action	Description
`Arrow Right`	Next star	Increases rating by 1
`Arrow Left`	Previous star	Decreases rating by 1
`Home`	First star	Sets rating to 1
`End`	Last star	Sets rating to maximum
`Space/Enter`	Confirm	Confirms current rating selection

Common gotchas

Star count changes: Changing the max prop after mount can cause rating value inconsistencies. Either reset the value when changing max or validate that existing values don't exceed the new maximum.

Icon sizing issues: Custom icons must accept a size prop for consistent scaling. Lucide icons work perfectly, but custom SVGs need to implement size-based width/height attributes.

Form integration timing: When using with form libraries, ensure the rating component's name prop matches your form schema. The hidden input updates synchronously with rating changes for proper validation.

Hover state conflicts: On touch devices, hover states can persist after touch. The component handles this, but custom CSS hover styles might interfere with touch interactions.

Accessibility overrides: Custom styling can interfere with accessibility features. Ensure sufficient color contrast and don't remove focus indicators when customizing appearance.

Controlled vs uncontrolled: Mixing controlled and uncontrolled usage patterns can cause state synchronization issues. Choose one pattern and stick with it throughout your component hierarchy.

Explore other interactive button components for React applications:

React Rating Button

Why most rating components feel disconnected

Installation

Examples

Style Variations

Interactive States

Features

Use Cases

API Reference

Rating

RatingButton

Rating States

Keyboard Navigation

Common gotchas

You might also like

Icon Button

Counter Button

Flip Button

Liquid Button

Questions developers actually ask

On this page

React Rating Button

Reactrating

Reactrating

Reactrating

Icon Button

Counter Button

Flip Button

Liquid Button

How do I integrate with React Hook Form or Formik?

Can I use custom icons instead of stars?

How do I implement half-star ratings?

How do I add validation and error states?

Does this work with server-side rendering?

How does touch interaction work on mobile devices?

On this page