Rating

Star rating control with optional half-star precision and a hover preview.

stable
since v0.1.0
2.09 kB
forms

Preview

tsx

import { Rating } from '@arshad-shah/cynosure-react';

export default function Example() {
  return <Rating defaultValue={3} max={5} label="Rate this product" />;
}

Sizes

Three sizes are available: sm, md (default), and lg.

Preview

Open

tsx

import { Rating } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
      <Rating size="sm" defaultValue={3} label="Small" />
      <Rating size="md" defaultValue={3} label="Medium" />
      <Rating size="lg" defaultValue={3} label="Large" />
    </div>
  );
}

Custom max

Set max to the number of stars to display. 5 is the default.

Preview

Open

tsx

import { Rating } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
      <Rating max={3} defaultValue={2} label="3-star" />
      <Rating max={5} defaultValue={4} label="5-star (default)" />
      <Rating max={10} defaultValue={7} label="10-star" />
    </div>
  );
}

Half stars

Set allowHalf to capture 0.5 increments — the click position within each star determines whether you commit a half or full.

Preview

Open

tsx

import { Rating } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
      <Rating allowHalf defaultValue={2.5} label="2.5 of 5" />
      <Rating allowHalf defaultValue={3.5} label="3.5 of 5" />
      <Rating allowHalf defaultValue={4.5} label="4.5 of 5" size="lg" />
    </div>
  );
}

Read-only and disabled

Set readOnly to render the value statically. disabled removes the field from the tab order.

Preview

Open

tsx

import { Rating } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
      <Rating defaultValue={4} label="Default" />
      <Rating defaultValue={4} label="Read-only" readOnly />
      <Rating defaultValue={4} label="Disabled" disabled />
    </div>
  );
}

With a value label

Use renderValue to render a trailing slot that reflects the current (or hovered) value.

Preview

Open

tsx

import { Rating } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Rating
      allowHalf
      defaultValue={4.5}
      max={5}
      label="Quality"
      renderValue={(value, max, preview) => (
        <span style={{ fontSize: '0.875rem', color: 'var(--c-fg-muted)' }}>
          {(preview ?? value).toFixed(1)} / {max}
        </span>
      )}
    />
  );
}

API

PropTypeDefaultDescription

value

number

—

Controlled current value, 0..`max`.

defaultValue

number

—

Uncontrolled initial value.

onValueChange

((value: number) => void)

—

Fires when the user clicks or keys to a new value.

max

number

Maximum number of stars.

allowHalf

boolean

false

Allow half-star increments.

size

"sm"|"md"|"lg"

"md"

Control size.

disabled

boolean

false

Disables interaction and removes the control from the tab order.

readOnly

boolean

false

Renders stars but blocks user interaction.

required

boolean

—

Marks the field as required for form submission.

name

string

—

Submitted form field name (renders a hidden input).

string

—

label

string

"Rating"

Accessible label.

aria-label

string

—

renderValue

((value: number, max: number, previewValue: number) => ReactNode)

—

Render a trailing slot (e.g. numeric label). `previewValue` is the currently-hovered value, or `undefined` when not hovering.

className

string

—

style

CSSProperties

—

Accessibility

The root exposes role="slider" with aria-valuemin={0}, aria-valuemax={max}, and aria-valuenow.
Keyboard: Arrow Up/Right and Down/Left adjust by step (1 by default, 0.5 when allowHalf); Home/End jump to bounds.
readOnly sets aria-readonly; disabled sets aria-disabled and removes the field from the tab order.
Clicking the active value again clears the rating (sets it back to 0).

Recipes

Use defaultValue for review forms; switch to controlled (value/onValueChange) when the value lives in form state.
Provide a clear label or aria-label so screen readers announce what is being rated.
Use renderValue to surface a numeric readout (e.g. “4.5 / 5”) next to the stars.