Rating

Import

import { Rating } from 'heroui-native-pro';

Anatomy

<Rating>
  <Rating.Item value={1} />
  <Rating.Item value={2} />
  <Rating.Item value={3} />
  <Rating.Item value={4} />
  <Rating.Item value={5} />
</Rating>

• Rating: Root container built on heroui-native's RadioGroup. Manages the numeric value, auto-renders items from 1 to maxValue when children are omitted, and propagates size/icon/read-only state via context.
• Rating.Item: Individual rating item. Wraps RadioGroup.Item and renders the default icon plus a clipped overlay for partial fills. Supports render-function children for fully custom indicators.

Usage

Basic usage

Auto-renders 5 items and calls onValueChange with the selected integer value.

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

<Rating value={value} onValueChange={setValue} />;

Uncontrolled

<Rating defaultValue={4} />

Sizes

Control item size with the size prop.

<Rating size="sm" defaultValue={4} />
<Rating size="md" defaultValue={4} />
<Rating size="lg" defaultValue={4} />

Read-only fractional

isReadOnly disables interaction and enables fractional fills (e.g. 3.5, 4.2). The partial fill is achieved by clipping a second copy of the icon, so any solid-fill icon can be used.

<Rating isReadOnly value={4.5} />
<Rating isReadOnly value={3.25} />

Max value

Ratings are not limited to 5 items — set maxValue to render any number of items.

<Rating maxValue={10} defaultValue={7} size="sm" />

Disabled

<Rating isDisabled value={3} />

Custom icon

Pass an icon prop with any SVG component. The component is expected to accept size, color, and colorClassName props so Rating can drive its dimensions and active / inactive colors. Wrap the SVG with withUniwind to enable colorClassName:

import type { FC } from 'react';
import Svg, { Path, type SvgProps } from 'react-native-svg';
import { withUniwind } from 'uniwind';

interface HeartIconProps extends SvgProps {
  size?: number;
  color?: string;
  colorClassName?: string;
}

const HeartIconBase: FC<HeartIconProps> = ({
  size = 24,
  color = 'currentColor',
  ...rest
}) => (
  <Svg width={size} height={size} viewBox="0 0 24 24" fill="none" {...rest}>
    <Path d="M12 21s-7-4.35-9.5-9.2..." fill={color} />
  </Svg>
);

const HeartIcon = withUniwind(HeartIconBase, {
  color: { fromClassName: 'colorClassName', styleProperty: 'accentColor' },
});

<Rating icon={<HeartIcon />} defaultValue={3} />;

Customizing icon size and colors

Use iconProps on the root to override size and active / inactive colors for every item. When both a raw color (activeColor / inactiveColor) and a className (activeColorClassName / inactiveColorClassName) are provided, the className wins for theme-aware styling.

<Rating
  icon={<HeartIcon />}
  iconProps={{
    size: 28,
    activeColorClassName: 'accent-danger',
    inactiveColorClassName: 'accent-muted/20',
  }}
  defaultValue={3}
/>

Custom indicator

Pass a render-function child to Rating.Item for a fully custom indicator. The function receives { isActive, isPartial, partialPercent }.

<Rating>
  {[1, 2, 3, 4, 5].map((itemValue) => (
    <Rating.Item key={itemValue} value={itemValue}>
      {({ isActive, partialPercent }) => (
        <View className="size-9 rounded-full items-center justify-center bg-muted/10">
          <Text className={isActive ? 'text-warning' : 'text-muted'}>
            {partialPercent > 0 && partialPercent < 100
              ? `${(itemValue - 1 + partialPercent / 100).toFixed(1)}`
              : itemValue}
          </Text>
        </View>
      )}
    </Rating.Item>
  ))}
</Rating>

Example

import { Rating } from 'heroui-native-pro';
import { Text, View } from 'react-native';
import { useState } from 'react';

export default function RatingExample() {
  const [value, setValue] = useState(4);

  return (
    <View className="items-center gap-2">
      <Rating value={value} onValueChange={setValue} />
      <Text className="text-muted text-sm">Rating: {value}</Text>
    </View>
  );
}

API Reference

Rating

Extends heroui-native RadioGroup except for value, defaultValue, onValueChange, and children which are overridden to accept numeric ratings.

RatingIconProps

Shared icon styling forwarded to the default star or any custom icon component. When both a raw color and a className are set, the className wins — the raw color is used as a fallback.

Rating.Item

The underlying pressable is an animated RadioGroup.Item that plays a subtle scale animation on press. Customize or disable it via the animation prop (or disable animated styles entirely with isAnimatedStyleActive={false}).

Extends heroui-native RadioGroup.Item except for value and children which are overridden.

RatingItemRenderProps

RatingItemAnimation

Animation configuration for the item press-scale feedback. Can be:

• false or 'disabled': Disable the item press animation
• undefined: Use default animation
• object: Custom animation configuration

Hooks

useRating

Hook to access the Rating context. Must be used within a Rating component.

import { useRating } from 'heroui-native-pro';

const { value, maxValue, size, isReadOnly, isDisabled, iconProps } =
  useRating();

Returns