Frost UI StarRating

Accessible star-rating control for Frost UI with fractional values, configurable ranges and star counts, tooltips, keyboard navigation, mouse and touch input, and RTL support.

Highlights

Native number input remains the form control and source of truth
Integer, fractional, exponent, and unrestricted step="any" values
Configurable minimum, maximum, star count, rating text, and five sizes
Keyboard, mouse, touch drag, and optional hover-preview interaction
Direction-aware filling, pointer values, and horizontal keys in RTL
Accessible slider state, native labels, required and disabled state, and display-only mode
Frost UI v4 light, dark, system, reduced-motion, focus, and forced-colors presentation
Native StarRating class and starrating fQuery plugin
Existing-instance reuse with frozen resolved options
Reversible disposal that restores the input's original visibility and tabindex
Prebuilt ESM and UMD bundles plus expanded and minified CSS, all with source maps
JSDoc-powered IntelliSense

Installation

Browser projects / bundlers

Install StarRating with its Frost UI v4 and fQuery v5 peers:

npm i @fr0st/ui-starrating @fr0st/ui @fr0st/query

The package root resolves to the compiled ESM bundle. Import both required stylesheets and the default component export:

import '@fr0st/ui/dist/frost-ui.min.css';
import '@fr0st/ui-starrating/dist/frost-ui-starrating.min.css';
import StarRating from '@fr0st/ui-starrating';

const rating = StarRating.init(
    document.querySelector('#product-rating'),
    {
        stars: 5,
        step: .5,
    },
);

@fr0st/ui and @fr0st/query are peer dependencies so the component shares the application's UI and fQuery instances. The package root, dist/*, and src/* are available through package exports.

StarRating requires a browser DOM or a compatible DOM environment configured through fQuery. Server-rendered applications should load the component on the client.

Browser (ESM)

The ESM bundle imports @fr0st/ui and @fr0st/query. Frost UI and fQuery also require @fr0st/core, so map all three dependencies when loading the bundle directly in a browser:

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@fr0st/ui@latest/dist/frost-ui.min.css">
<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@fr0st/ui-starrating@latest/dist/frost-ui-starrating.min.css">

<script type="importmap">
{
    "imports": {
        "@fr0st/core": "https://cdn.jsdelivr.net/npm/@fr0st/core@latest/dist/frost-core.esm.min.js",
        "@fr0st/query": "https://cdn.jsdelivr.net/npm/@fr0st/query@latest/dist/fquery.esm.min.js",
        "@fr0st/ui": "https://cdn.jsdelivr.net/npm/@fr0st/ui@latest/dist/frost-ui.esm.min.js"
    }
}
</script>
<script type="module">
    import StarRating from 'https://cdn.jsdelivr.net/npm/@fr0st/ui-starrating@latest/dist/frost-ui-starrating.esm.min.js';

    StarRating.init(document.querySelector('#product-rating'));
</script>

Browser (UMD)

Load Frost UI's all-in-one bundle before StarRating. The UI bundle supplies both the UI and fQuery globals expected by the component:

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@fr0st/ui@latest/dist/frost-ui.min.css">
<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@fr0st/ui-starrating@latest/dist/frost-ui-starrating.min.css">

<script src="https://cdn.jsdelivr.net/npm/@fr0st/ui@latest/dist/frost-ui-bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@fr0st/ui-starrating@latest/dist/frost-ui-starrating.min.js"></script>
<script>
    const rating = UI.StarRating.init(
        document.querySelector('#product-rating'),
    );
</script>

The UMD bundle adds StarRating to the existing globalThis.UI object. It expects globalThis.UI and globalThis.fQuery to exist before it loads. If the non-bundled Frost UI build is used instead, load fQuery, Frost UI, and StarRating in that order.

Do not load the separate fQuery script when using frost-ui-bundle.js or frost-ui-bundle.min.js.

Usage

Start with a normal number input and an explicit or wrapping label. StarRating inserts the visible slider immediately before the input and visually hides the original control while keeping its value synchronized for forms:

<label for="product-rating">Product rating</label>
<input
    id="product-rating"
    name="rating"
    type="number"
    min="1"
    max="5"
    step="0.5"
    value="3.5"
    required>

import StarRating from '@fr0st/ui-starrating';

const rating = StarRating.init(
    document.querySelector('#product-rating'),
    {
        ratingText(value) {
            return `${value} out of 5 stars`;
        },
    },
);

console.log(rating.getValue()); // 3.5

Calling StarRating.init() again for the same input returns its existing instance. Dispose the current instance before reinitializing the input with different options.

Options

Component options are resolved in this order:

StarRating.defaults
The input's data-ui-* attributes
Options passed to StarRating.init()

Resolved instance.options are frozen. Native input state is applied during initialization without modifying that object: min, max, and step attributes override their matching resolved options; native readonly enables display-only behavior; and the input's current value supplies the initial rating. The initial disabled and required state, accessible label attributes, associated labels, and direction also come from the input and its DOM context.

Dispose and reinitialize to apply changes to the range, step, read-only mode, labels, or direction; use disable() and enable() to change disabled state.

Option	Type	Default	Description
`animate`	`boolean`	`true`	Animate committed rating changes using Frost UI transition tokens.
`displayOnly`	`boolean`	`false`	Present a focusable, read-only rating without editing handlers. Native `readonly` also enables this mode.
`hover`	`boolean`	`true`	Preview the pointer rating without committing it.
`max`	`number \| null`	`null`	Set the effective maximum. `null` uses the rendered star count.
`min`	`number`	`0`	Set the effective minimum.
`ratingText`	`(rating: number) => string`	Singular/plural star text	Create tooltip content and `aria-valuetext`.
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Select the component font size.
`stars`	`number`	`5`	Set the number of rendered stars. Values are normalized to a positive integer.
`step`	`number \| 'any'`	`1`	Set the rating increment. `'any'` allows unrestricted finite values.
`tooltip`	`boolean`	`true`	Show rating text during focus, hover, and drag interaction.

const rating = StarRating.init(node, {
    animate: true,
    displayOnly: false,
    hover: true,
    max: 8,
    min: 2,
    ratingText: (value) => `Score ${value} of 8`,
    size: 'lg',
    stars: 10,
    step: .25,
    tooltip: true,
});

The effective range is clamped between zero and the rendered star count. Finite values are clamped to that range. Numeric steps are anchored at the effective minimum, and intermediate values advance to the next valid step; the exact minimum and maximum remain selectable. Decimal and exponent steps are supported within JavaScript numeric precision. When a step is too small for reliable snapping, the clamped value is retained instead of introducing rounding drift or an invalid value. Invalid or non-finite programmatic values are ignored, and invalid steps safely behave like step="any".

Data attributes

Options other than ratingText can be supplied through data-ui-* attributes:

Attribute	Example
`data-ui-animate`	`data-ui-animate="false"`
`data-ui-display-only`	`data-ui-display-only="true"`
`data-ui-hover`	`data-ui-hover="false"`
`data-ui-max`	`data-ui-max="8"`
`data-ui-min`	`data-ui-min="2"`
`data-ui-size`	`data-ui-size="lg"`
`data-ui-stars`	`data-ui-stars="10"`
`data-ui-step`	`data-ui-step="0.25"`
`data-ui-tooltip`	`data-ui-tooltip="false"`

<input
    id="product-rating"
    type="number"
    data-ui-toggle="starrating"
    data-ui-size="lg"
    data-ui-stars="10"
    min="2"
    max="8"
    step="0.25"
    value="6.5">

The component still needs to be initialized through the class or fQuery plugin. The demo uses data-ui-toggle="starrating" as a shared initialization selector:

$('[data-ui-toggle="starrating"]').starrating();

The data-ui-toggle attribute does not initialize StarRating by itself. Use native min, max, step, and readonly when those constraints are part of the input's form semantics.

Methods

Method	Returns	Description
`StarRating.init(node, options?)`	`StarRating`	Return the existing instance for an input or create one.
`disable()`	`void`	Disable the number input, cancel dragging and hover previews, restore the committed rating, and remove the slider from the tab order.
`dispose()`	`void`	Remove generated markup and events, unregister component state, and restore the original input.
`enable()`	`void`	Enable the number input and restore slider interaction.
`getValue()`	`number \| null`	Return the current finite rating, or `null` when the input is empty or invalid.
`setValue(value)`	`void`	Normalize, clamp, snap, display, and commit a finite rating.

rating.setValue(4.5);
console.log(rating.getValue()); // 4.5

rating.disable();
rating.enable();
rating.dispose();

An instance exposes its original input as instance.node and its frozen resolved configuration as instance.options. Both become null after disposal.

dispose() restores the input's original visually-hidden state, aria-hidden, and tabindex, preserves its current value and disabled state and unrelated classes, and removes generated label IDs only if the application has not changed them. The input can then be initialized again with new options. Removing the original input through fQuery also disposes the component automatically.

Events

StarRating emits one namespaced fQuery event from the original number input when a component-driven action commits a distinct normalized rating:

Event	Description
`change.ui.starrating`	The value changed through keyboard, mouse, touch, or `setValue()`.

import $ from '@fr0st/query';

$.addEvent(
    '#product-rating',
    'change.ui.starrating',
    (event) => {
        console.log(event.currentTarget.value);
    },
);

The underlying event type is change; fQuery exposes event.namespace as ui.starrating. Setting or selecting the current normalized value again does not emit another event. Hover preview changes only the visible fill and tooltip; it does not commit a value or change the slider's accessible value. A change event dispatched on the input refreshes the rendered control from the native value.

Native form resets cancel active dragging and refresh the visible rating, accessible value, and tooltip after the browser restores the input, without emitting a change event. This also works for read-only ratings and inputs associated with an external form through the form attribute. Canceled resets leave the current interaction intact.

Calling disable() stops an active drag, clears any hover preview, and restores the latest committed rating and tooltip text without emitting a change event. If a focus or change handler disables or disposes the component during drag startup, startup stops.

fQuery API

Importing StarRating registers starrating on fQuery.QuerySet:

import $ from '@fr0st/query';
import '@fr0st/ui-starrating';

const rating = $('#product-rating').starrating({
    size: 'lg',
    step: .5,
});

$('#product-rating').starrating('setValue', 4.5);

const value = $('#product-rating').starrating('getValue');

$('#product-rating').starrating('disable');
$('#product-rating').starrating('enable');
$('#product-rating').starrating('dispose');

Pass an options object to initialize every matched input, or pass a public method name followed by its arguments. The first component or method result is returned.

Accessibility and keyboard behavior

The rendered control uses role="slider" with aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext, aria-required, aria-readonly, and aria-disabled.
Explicit labels, wrapping labels, multiple labels, and existing aria-labelledby references contribute to the rendered slider's accessible name.
An input aria-label is copied when no label references are available.
Labels without IDs receive temporary generated IDs while the component is active.
The rendered slider enters the tab order while the original input becomes visually hidden and receives aria-hidden="true" and tabindex="-1", leaving one control exposed to assistive technology. Focus on the original input is forwarded to the slider, including when the input is already focused during initialization.
Arrow Up and Arrow Down increase and decrease by one step. Arrow Left and Arrow Right are direction-aware. Page Up and Page Down use the larger of one rating point or one step, subject to step snapping and range limits. Home and End select the effective minimum and maximum.
Handled slider keys prevent page scrolling.
Disabled ratings leave the tab order and ignore keyboard and pointer interaction.
Display-only and native read-only ratings expose aria-readonly="true", remain focusable, and do not install editing handlers.
The original input remains the submitted form field and preserves native value, required, disabled, min, max, and step semantics.

Applications remain responsible for a meaningful label, instructions, validation feedback, and sufficient contrast when overriding the component color. ratingText should describe the rating in the surrounding language and scale.

Customization

The public static defaults, classes, icons, and lang objects can be customized before initialization:

StarRating.defaults.tooltip = false;
StarRating.lang.star = 'point';
StarRating.lang.stars = 'points';
StarRating.icons.filled = '<svg aria-hidden="true" ...></svg>';
StarRating.icons.outline = '<svg aria-hidden="true" ...></svg>';

StarRating.classes exposes the generated class names for animation, the slider container, disabled state, filled and outline layers, and input hiding. Custom icons should remain decorative because the slider's accessible value comes from ARIA and ratingText.

The component stylesheet exposes these CSS custom properties:

Property	Purpose
`--ui-starrating-font-size`	Star size for the current variant.
`--ui-starrating-color`	Outline and fill color.
`--ui-starrating-focus-box-shadow`	Focus-visible ring.
`--ui-starrating-disabled-opacity`	Disabled opacity.

.product-score .starrating {
    --ui-starrating-color: var(--ui-success);
}

Themes and RTL

StarRating combines its component stylesheet with Frost UI v4 transition, focus-ring, disabled, and reduced-motion tokens. Frost UI follows the user's preferred color scheme by default. Set data-ui-theme="light" or data-ui-theme="dark" on the document or an ancestor to select a theme explicitly:

<section data-ui-theme="dark">
    <label for="dark-rating">Dark theme rating</label>
    <input id="dark-rating" type="number" value="4">
</section>

Normal document and ancestor direction is respected. A dir attribute placed directly on the original input is copied to the rendered slider:

<input id="rtl-rating" type="number" value="4" dir="rtl">

In RTL layouts, fill begins at the inline start, pointer values are mirrored, and Arrow Left increases while Arrow Right decreases. Vertical keys, Home, End, and Page keys retain their normal meaning. Forced-colors mode replaces the star and focus colors with system colors.

Development

Use Node.js matching ^20.19.0 || ^22.13.0 || >=24. Install dependencies with npm ci, then install Playwright browsers with npx playwright install --with-deps.

npm test
npm run lint
npm run build

npm test rebuilds JavaScript and CSS, then runs the Playwright suite in Chromium, Firefox, and WebKit. npm run test:browser runs the suite against the existing bundles, so rebuild after changing source files.

After building, npm run test:coverage runs Chromium tests and writes coverage reports to coverage/.

npm run test:headed and npm run test:ui also use the existing bundles and open headed browsers or the Playwright UI.

npm run lint:sass:unused checks for unused Sass variables.

License

Frost UI StarRating is released under the MIT License.

Name		Name	Last commit message	Last commit date
.github		.github
demo		demo
dist		dist
src		src
test		test
.gitignore		.gitignore
.npmrc		.npmrc
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
playwright.config.js		playwright.config.js
playwright.coverage.config.js		playwright.coverage.config.js
postcss.config.js		postcss.config.js
stylelint.config.js		stylelint.config.js
vite.config.js		vite.config.js

Navigation Menu

Repository files navigation

Frost UI StarRating

Highlights

Installation

Browser projects / bundlers

Browser (ESM)

Browser (UMD)

Usage

Options

Data attributes

Methods

Events

fQuery API

Accessibility and keyboard behavior

Customization

Themes and RTL

Development

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Frost UI StarRating

Highlights

Installation

Browser projects / bundlers

Browser (ESM)

Browser (UMD)

Usage

Options

Data attributes

Methods

Events

fQuery API

Accessibility and keyboard behavior

Customization

Themes and RTL

Development

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages