All components
Data Display
Rating
stable
Since 1.2
Interactive star rating, plus a composed award badge pairing a score with title, subtitle, and review metadata.
Data Display
primitive
Display
Documented
import { Rating } from '@ivim/native/components';
When to use
Use when
Collecting a whole-star rating from someone.
Displaying an average score with its review count, using RatingBadge.
Don't use when
The scale is continuous or wide — use Slider, which announces a numeric value.
The value is a binary reaction — use a toggle or an icon button.
Playground
Adjust the controls to preview live prop combinations. The code snippet updates to match the current selection.
Read only
isReadOnly
<Rating />
Example
Preview
Code
Rating
Interactive
Read only
Empty
Ten stars
RatingBadge
Score with reviews
4.7
1,204 reviews
With a title and subtitle
4.7
Ivim Health
Verified patients
1,204 reviews
A single review
5
New listing
1 review
Custom count wording
4.4
86 verified visits
Fractional values
Fractional ratings are display-only, deliberately. An average of 4.7 is worth showing but is not something a person can express by tapping, so the stars round for display while the exact score is stated in text — and the accessible name carries the precise value, not the rounded one.
Anatomy
The parts that compose this component.
1
Stars
Filled and empty stars; each is a press target when interactive.
2
Score
RatingBadge only — the exact numeric value.
3
Title and subtitle
RatingBadge only — what is being rated.
4
Review count
RatingBadge only, formatted and localised.
Guidelines
Do
Use RatingBadge for averages: it states the exact score in text, so 4.7 is not rounded away.
Do
Set isReadOnly for any rating the user is not being asked to change.
Don't
Expect people to express a fractional rating by tapping — interaction is whole-star by design.
Don't
Show stars without the underlying number when the exact value matters.
Props
Public props for this component. Required props are marked; defaults reflect the component implementation.
value / defaultValue
number
Controlled and uncontrolled rating.
onChange
(value: number) => void
Fires with the selected whole-star value.
max
number
default: 5
Number of stars.
isReadOnly
boolean
default: false
Display only. Announces as an image rather than an adjustable control.
RatingBadge: title / subtitle
ReactNode
What is being rated, and a supporting line.
RatingBadge: reviewCount / formatReviewCount
number / (count) => string
Review total, and a hook for other units or locales.
aria-label
string
Accessible name when there is no visible label, or when the label is not plain text.
size
number
default: 20
Star size in pixels.
Accessibility
Roles and screen-reader behavior this component provides, plus keyboard interactions.
•
An interactive rating announces as adjustable with its current value; each star is a named press target ("4 stars").
•
A read-only rating announces as an image with its value, so the score is available without implying it can be changed.
•
RatingBadge states the precise score in its accessible name — an average of 4.7 must not be announced as the rounded 5 the stars show.
•
The stars inside RatingBadge are hidden from assistive tech, since the badge name already carries the score.
Tab
Moves focus across the stars when interactive.
Space / Enter
Selects the focused star.
Platform & RTL
Behavior that differs across the platforms this component runs on.
Web
Each interactive star is focusable with an inset focus ring.
iOS
VoiceOver announces the adjustable value; each star is separately reachable.
Android
TalkBack announces the value.
RTL
Stars fill from the start edge, mirroring with the writing direction.
State coverage
Interaction and visual states this component supports.
base
semantic color
density
Token references
Semantic design tokens this component page exercises. Tap one to edit it live.
Related components
Components that solve adjacent problems or compose with this one.
Badge
Compact status or metadata label with six semantic tones plus seven non-semantic accent tones, four treatments, a pill or square shape, three sizes, dots, counts, adornments, and optional press and remove actions.
Progress
Linear and circular progress with four label placements, full-ring and half-gauge shapes, and a distinct indeterminate state.
Slider
Range input with one or two thumbs, supporting drag, keyboard, and assistive-technology adjustment with step snapping and value announcement.
Avatar
Person or entity representation with image, initials, and placeholder states, six sizes, presence, verified, and custom badge overlays.