Documentation and live examples v1.0.0

universal-rating

A framework-agnostic rating UI for JavaScript, Angular, React, Vue, Web Components, and static HTML.

Download & install

Install the universal rating package. It has no Angular, React, or Vue runtime dependency.

npm install universal-rating

Usage

Use the root import for JavaScript APIs, or register the Web Component for HTML usage.

import { starRate } from 'universal-rating';

const rating = starRate.create('#rating', {
  value: 3.5,
  max: 5,
  precision: 0.5,
  icon: 'star',
  onChange: value => console.log(value)
});

<form id="review-form">
  <universal-rating
    name="rating"
    theme="bootstrap"
    labels="Poor,Fair,Good,Very good,Excellent"
    show-label
    required
    clearable
    error-text="Please select a rating"
  ></universal-rating>

  <button type="submit">Submit review</button>
</form>

Registered Web Components are form-associated through ElementInternals when supported. Older browsers and starRate.create() DOM instances keep the hidden-input fallback.

Examples

Each row renders the real package output and keeps the copyable setup beside it.

Last resultTry a rating example

Basic rating

A clean five-star rating with a starting value.

starRate.create('#basic-rating', {
  value: 3,
  max: 5,
  precision: 1
});

Decimal rating

Half-step precision for reviews and scores.

starRate.create('#decimal-rating', {
  value: 3.5,
  max: 5,
  precision: 0.5
});

Rating meaning labels

Show user-friendly labels such as Poor, Good, or Excellent while users hover, tap, drag, use the keyboard, or select a rating.

starRate.create('#rating-meaning', {
  value: 4,
  labels: ['Poor', 'Fair', 'Good', 'Very good', 'Excellent'],
  showLabel: true
});

RTL support

Use right-to-left visual direction, pointer math, and horizontal keyboard controls for global products.

starRate.create('#rtl-rating', {
  value: 3,
  dir: 'rtl',
  labels: ['ضعيف', 'مقبول', 'جيد', 'جيد جدا', 'ممتاز'],
  showLabel: true
});

Readonly rating

Display a score without allowing changes.

starRate.create('#readonly-rating', {
  value: 4.5,
  readonly: true
});

Readonly product card

Render a compact static score with one icon, the numeric value, and review count.

starRate.create('#readonly-product-card', {
  value: 4.5,
  readonly: true,
  showValue: true,
  count: 245,
  suffix: 'reviews',
  theme: 'material',
  icon: 'heart'
});

Disabled rating

Temporarily block pointer and keyboard changes.

starRate.create('#disabled-rating', {
  value: 2.5,
  disabled: true
});

Custom colors

Use one brand color and a custom empty color.

starRate.create('#custom-colors', {
  value: 4,
  color: '#e1085d',
  emptyColor: '#d7dee9',
  spacing: '6px'
});

Styling hooks

Attach classes to the root, items, icons, visible label, and validation error slots.

starRate.create('#styled-rating', {
  value: 4,
  customClass: {
    root: 'review-rating',
    item: 'review-rating__item',
    icon: 'review-rating__icon',
    label: 'review-rating__label',
    error: 'review-rating__error'
  }
});

Icon variants

Use heart, circle, diamond, or star shapes.

starRate.create('#icon-variants', {
  value: 4,
  icon: 'heart',
  color: '#ef4f86'
});

Custom SVG icon

Provide a safe SVG string for a custom shape.

starRate.create('#custom-svg', {
  value: 4,
  icon: 'custom',
  customIcon: '<svg viewBox="0 0 24 24">...</svg>'
});

Clear rating

Let users click the selected rating again to reset a form value back to zero.

starRate.create('#clear-rating', {
  value: 3,
  clearable: true
});

Better events

Track hover, focus, blur, clear, and change behavior for analytics or advanced UI.

starRate.create('#rating-events', {
  value: 3,
  clearable: true,
  onHover: value => console.log('hover', value),
  onFocus: () => console.log('focus'),
  onBlur: () => console.log('blur'),
  onClear: () => console.log('clear')
});

Required validation

Show accessible inline validation when a required review or survey rating is empty.

starRate.create('#required-validation', {
  required: true,
  errorText: 'Please select a rating'
});

Form value

Set name to submit the rating. The Web Component uses ElementInternals when available; starRate.create() uses a hidden-input fallback.

starRate.create('#form-value', {
  value: 5,
  name: 'rating'
});

Migration aliases

Old angular-star names still work during migration.

starRate.create('#legacy-aliases', {
  value: 3.5,
  length: 5,
  fractions: true,
  iconType: 'diamond'
});

Theme presets

Use a preset when you need the rating to look finished quickly. Direct color options still override the preset.

default theme

Balanced package defaults for general product UI.

starRate.create('#theme-default', {
  value: 4,
  theme: 'default'
});

minimal theme

Quiet monochrome styling for dashboards and admin tools.

starRate.create('#theme-minimal', {
  value: 4,
  theme: 'minimal'
});

material theme

Material-inspired green, orange, red, and blue-gray tones.

starRate.create('#theme-material', {
  value: 4,
  theme: 'material'
});

bootstrap theme

Bootstrap-style success, warning, danger, and neutral colors.

starRate.create('#theme-bootstrap', {
  value: 4,
  theme: 'bootstrap'
});

outline theme

Crisp blue selection color with restrained empty outlines.

starRate.create('#theme-outline', {
  value: 4,
  theme: 'outline'
});

filled theme

Expressive filled colors for friendlier review experiences.

starRate.create('#theme-filled', {
  value: 4,
  theme: 'filled'
});

Framework Workbench

Choose your stack to see the right lifecycle pattern, live preview when the platform supports DOM, and copyable code.

Web

SSR / meta

Hybrid mobile

Native / headless

JavaScript

Use a normal DOM element when you are not using a framework.

DOM

LifecycleCreate after the element exists; call destroy() if you remove the host manually.

import { starRate } from 'universal-rating';

const rating = starRate.create('#rating', {
  value: 4,
  precision: 0.5,
  labels: ['Poor', 'Fair', 'Good', 'Very good', 'Excellent'],
  showLabel: true,
  onChange: value => console.log(value)
});

Web

JavaScriptDOM
HTML / Web ComponentWeb Component
AngularDOM
ReactDOM
VueDOM
SvelteDOM
SolidDOM
PreactDOM
LitWeb Component
AlpineDOM
EmberDOM

SSR / meta

Next.jsSSR client-only
NuxtSSR client-only
AstroSSR client-only
SvelteKitSSR client-only
QwikSSR client-only

Hybrid mobile

Ionic AngularMobile WebView
Ionic ReactMobile WebView
Ionic VueMobile WebView
CapacitorMobile WebView
CordovaMobile WebView

Native / headless

React NativeHeadless
ExpoHeadless

Configuration parameters

Pass these options to starRate.create(). Migration aliases are supported for old angular-star config names.

Option	Default	What it does
`value`	`0`	Initial selected rating value.
`max`	`5`	Maximum rating item count.
`precision`	`0.5`	Step size for click, hover, and keyboard updates.
`dir`	`ltr`	Visual and interaction direction: ltr or rtl.
`theme`	`default`	Visual preset: default, minimal, material, bootstrap, outline, or filled. Explicit color options override theme colors.
`icon`	`star`	star, heart, circle, diamond, or custom.
`customIcon`	`''`	SVG string used when icon is custom.
`color`	`''`	Single fill color override.
`badColor / avgColor / goodColor`	`red / amber / green`	Score-based fill colors when color is not set.
`emptyColor`	`#cbd5e1`	Unfilled icon color.
`spacing`	`0px`	Gap between rating icons.
`size`	`medium`	extra-small, small, medium, large, extra-large, or custom.
`customSize`	`30px`	Exact size used when size is custom.
`readonly`	`false`	Display value without interaction.
`showValue`	`false`	For readonly ratings, render a compact summary with one icon and the value.
`count`	`undefined`	Optional count shown beside a readonly compact summary.
`suffix`	`''`	Optional label appended to count, such as reviews.
`disabled`	`false`	Disable focus and interaction.
`clearable`	`false`	Click the current value again to reset to zero.
`required`	`false`	Require a value greater than zero for forms.
`errorText`	`Please select a rating`	Inline validation message for required ratings.
`label`	`Rating`	Accessible label for the slider.
`labels`	`[]`	Meaning text from low to high, such as Poor through Excellent.
`showLabel`	`false`	Show the matching meaning text for the current preview or selected value.
`name`	`''`	Form field name. Web Components use ElementInternals when supported; DOM instances render a hidden input fallback.
`className`	`''`	Extra class on the root rating control.
`customClass`	`undefined`	Slot classes for root, item, icon, visible label, and validation error.
`onChange`	`undefined`	Called with the new value after user changes.
`onHover`	`undefined`	Called when hover or drag preview moves to a new value.
`onFocus`	`undefined`	Called when the slider control receives focus.
`onBlur`	`undefined`	Called when the slider control loses focus.
`onClear`	`undefined`	Called when a non-zero value is cleared to zero.
`length / fractions / iconType`	`aliases`	Migration aliases for max, precision, and icon.

Methods

Keep the returned instance if you need to update the rating after rendering.

Method	Purpose
`setValue(value)`	Set the selected value and update the UI.
`getValue()`	Read the current selected value.
`update(options)`	Patch options and re-render.
`clear()`	Reset the selected value to zero.
`validate()`	Show required validation and return whether the rating is valid.
`enable()`	Clear disabled state.
`disable()`	Set disabled state.
`focus()`	Focus the accessible slider control.
`destroy()`	Remove rendered DOM from the target.
`valueFromPosition(x, width, options)`	Headless rating value helper for React Native and custom renderers.
`roundValue(value, precision)`	Round a value to the configured rating precision.
`clampValue(value, max)`	Clamp a value between zero and the maximum rating.

Events

Use callbacks for the JavaScript API and CustomEvents for the Web Component.

Event	Meaning
`onChange(value)`	JavaScript callback passed to starRate.create().
`onHover(value)`	JavaScript callback when hover or drag preview changes.
`onFocus()`	JavaScript callback when the rating receives focus.
`onBlur()`	JavaScript callback when the rating loses focus.
`onClear()`	JavaScript callback when the value clears to zero.
`universal-rating-change`	Web Component CustomEvent with detail.value.
`universal-rating-hover`	Web Component CustomEvent with detail.value for preview changes.
`universal-rating-focus`	Web Component CustomEvent with the current detail.value.
`universal-rating-blur`	Web Component CustomEvent with the current detail.value.
`universal-rating-clear`	Web Component CustomEvent with detail.value set to 0.

Accessibility

Rendered ratings use role="slider", ARIA value attributes, readable labels, disabled/readonly states, and keyboard controls: Arrow keys, Home, End, Enter, and Space.

Migration from angular-star

angular-star is replaced by universal-rating. Use max instead of length, precision instead of fractions, and icon instead of iconType. The aliases still work during migration.

Result log

readyRendered universal-rating docs