Rating

A star-based rating input that lets users select a score. Supports hover preview, keyboard navigation, readonly and disabled modes, and HTML form integration.

Features

⌨️ Keyboard Navigation — ←/→ arrows adjust value; Home/End jump to extremes
⭐ Configurable Stars — any number of stars via max (default 5)
🌈 6 Semantic Colors — primary, secondary, info, success, warning, error
📏 3 Sizes — sm, md, lg
🔒 Readonly & Disabled — readonly shows a non-interactive score; disabled removes from tab order
🧱 Solid Fill Mode — selected stars can render as solid-filled via solid
🔗 Form-Associated — name attribute & native form reset support
🖱️ Hover Preview — stars fill on hover before selection is committed

Source Code

View Source Code

import { computed, define, defineField, html, inject, signal } from '@vielzeug/craftit';
import { createSliderControl } from '@vielzeug/craftit/controls';

import type { DisablableProps, SizableProps, ThemableProps } from '../../types';

import '../../content/icon/icon';
import { coarsePointerMixin, colorThemeMixin, reducedMotionMixin, sizeVariantMixin } from '../../styles';
import { disablableBundle, sizableBundle, themableBundle } from '../shared/bundles';
import { mountFormContextSync } from '../shared/dom-sync';
import { FORM_CTX } from '../shared/form-context';
import styles from './rating.css?inline';

export type BitRatingEvents = {
  change: { originalEvent?: Event; value: number };
};

/** Rating props */
export type BitRatingProps = ThemableProps &
  SizableProps &
  DisablableProps & {
    /** Accessible group label */
    label?: string;
    /** Maximum rating (number of stars) */
    max?: number;
    /** Form field name */
    name?: string;
    /** Make rating read-only */
    readonly?: boolean;
    /** Render selected stars as solid-filled instead of outline-only */
    solid?: boolean;
    /** Current rating value */
    value?: number;
  };

/**
 * A star rating input.
 *
 * @element bit-rating
 *
 * @attr {number} value - Current rating value (default: 0)
 * @attr {number} max - Maximum number of stars (default: 5)
 * @attr {boolean} readonly - Read-only display mode
 * @attr {boolean} disabled - Disabled state
 * @attr {string} label - aria-label for the group (default: 'Rating')
 * @attr {string} color - Theme color for filled stars
 * @attr {string} size - 'sm' | 'md' | 'lg'
 * @attr {string} name - Form field name
 * @attr {boolean} solid - Fill selected stars (outline remains default when omitted)
 *
 * @fires change - Emitted when value changes. detail: { value: number, originalEvent?: Event }
 *
 * @cssprop --rating-star-size - Star diameter
 * @cssprop --rating-color-empty - Empty star color
 * @cssprop --rating-color-filled - Filled star color
 * @cssprop --rating-gap - Gap between stars
 *
 * @part stars - Stars container.
 * @part star - Star item element.
 * @example
 * ```html
 * <bit-rating value="3" max="5" color="warning"></bit-rating>
 * <bit-rating value="4" solid></bit-rating>
 * ```
 */
export const RATING_TAG = define<BitRatingProps, BitRatingEvents>('bit-rating', {
  formAssociated: true,
  props: {
    ...themableBundle,
    ...sizableBundle,
    ...disablableBundle,
    label: 'Rating',
    max: 5,
    name: undefined,
    readonly: false,
    solid: false,
    value: 0,
  },
  setup(props, { emit, host }) {
    const formCtx = inject(FORM_CTX);

    mountFormContextSync(host.el, formCtx, props);

    const normalizedValue = computed(() => {
      const max = Math.max(1, Number(props.max!.value) || 5);
      const raw = Number(props.value!.value);
      const safe = Number.isFinite(raw) ? raw : 0;

      return Math.min(max, Math.max(0, safe));
    });

    const fd = defineField({
      disabled: computed(() => Boolean(props.disabled!.value) || Boolean(formCtx?.disabled.value)),
      value: computed(() => String(normalizedValue.value || 0)),
    });

    const triggerValidation = (on: 'blur' | 'change') => {
      if (formCtx?.validateOn?.value === on) {
        fd.reportValidity();
      }
    };

    const isInteractive = computed(() => !props.readonly!.value && !(props.disabled!.value || formCtx?.disabled.value));
    const hovered = signal<number | null>(null);
    const displayValue = computed(() => hovered.value ?? normalizedValue.value);
    const getStarButtons = () => {
      return [...(host.el.shadowRoot?.querySelectorAll<HTMLButtonElement>('[data-star]') ?? [])];
    };
    const ratingControl = createSliderControl({
      max: () => Number(props.max!.value) || 5,
      min: () => 1,
      step: () => 1,
    });

    function spawnSparkles(star: number) {
      const layer = host.el.shadowRoot?.querySelector<HTMLElement>('.sparkle-layer');
      const btn = host.el.shadowRoot?.querySelector<HTMLElement>(`[data-star="${star}"]`);

      if (!layer || !btn) return;

      const cx = btn.offsetLeft + btn.offsetWidth / 2;
      const cy = btn.offsetTop + btn.offsetHeight / 2;
      const count = 10;

      for (let i = 0; i < count; i++) {
        const p = document.createElement('span');
        const angle = (360 / count) * i + (Math.random() * 30 - 15);
        const dist = 18 + Math.random() * 20;
        const size = 3 + Math.random() * 4;
        const dur = 380 + Math.random() * 220;

        p.className = 'sparkle';
        p.style.cssText = [
          `left:${cx}px`,
          `top:${cy}px`,
          `--_angle:${angle}deg`,
          `--_dist:${dist}px`,
          `width:${size}px`,
          `height:${size}px`,
          `--_dur:${dur}ms`,
          `animation-delay:${Math.random() * 60}ms`,
        ].join(';');
        layer.appendChild(p);
        p.addEventListener('animationend', () => p.remove(), { once: true });
      }
    }
    function select(star: number, originalEvent?: Event) {
      if (!isInteractive.value) return;

      const max = Math.max(1, Number(props.max!.value) || 5);
      const nextValue = Math.min(max, Math.max(0, star));

      if (nextValue === normalizedValue.value) return;

      // Write through the reactive prop signal; craftit handles host reflection.
      props.value!.value = nextValue;
      emit('change', { originalEvent, value: nextValue });
      triggerValidation('change');
      spawnSparkles(nextValue);
    }
    function handleKeydown(e: KeyboardEvent, star: number) {
      const next = ratingControl.nextFromKey(e.key, star);

      if (next == null) return;

      e.preventDefault();
      select(next, e);

      const buttons = getStarButtons();

      buttons[next - 1]?.focus();
    }

    const stars = computed(() => {
      const max = Number(props.max!.value) || 5;

      return Array.from({ length: max }, (_, i) => i + 1);
    });

    return () => html`
      <div class="stars" part="stars" role="radiogroup" :aria-label="${props.label}" :aria-required="${() => null}">
        ${() =>
          stars.value.map(
            (star) =>
              html`<button
                class="star-btn"
                part="star"
                type="button"
                role="radio"
                :aria-label="${() => `${star} ${star === 1 ? 'star' : 'stars'}`}"
                :aria-checked="${() => String(star === normalizedValue.value)}"
                :data-star="${star}"
                ?data-filled="${() => star <= displayValue.value}"
                :disabled="${() => (!isInteractive.value ? true : null)}"
                @click="${(e: Event) => select(star, e)}"
                @pointerenter="${() => {
                  if (isInteractive.value) hovered.value = star;
                }}"
                @pointerleave="${() => {
                  hovered.value = null;
                }}"
                @keydown="${(e: KeyboardEvent) => handleKeydown(e, star)}">
                <bit-icon name="star" size="var(--_star-size)" stroke-width="1.5" aria-hidden="true"></bit-icon>
              </button>`,
          )}
        <div class="sparkle-layer"></div>
      </div>
    `;
  },
  styles: [colorThemeMixin, sizeVariantMixin({}), coarsePointerMixin, reducedMotionMixin, styles],
});

Basic Usage

html

<bit-rating label="Product rating" value="3"></bit-rating>

<script type="module">
  import '@vielzeug/buildit';
</script>

Listen for changes:

html

<bit-rating id="rating" label="Rate this article" color="warning"></bit-rating>

<script type="module">
  import '@vielzeug/buildit';

  document.getElementById('rating').addEventListener('change', (e) => {
    console.log('Rating:', e.detail.value);
  });
</script>

Colors

Preview

Code

RTL

Sizes

Preview

Code

RTL

Custom Max

Preview

Code

RTL

Readonly

Use readonly to display a rating without allowing user interaction — useful for showing review scores.

Preview

Code

RTL

Solid Stars

Use solid to render selected stars as filled shapes instead of outline-only.

Preview

Code

RTL

Disabled

Preview

Code

RTL

API Reference

Attributes

Attribute	Type	Default	Description
`value`	`number`	`0`	Current selected rating
`max`	`number`	`5`	Total number of stars
`readonly`	`boolean`	`false`	Prevents user interaction; shows value only
`solid`	`boolean`	`false`	Fills selected stars instead of outline-only
`disabled`	`boolean`	`false`	Disables the rating input
`label`	`string`	—	Accessible label for the rating group
`name`	`string`	—	Form field name
`color`	`'primary' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'error'`	—	Star highlight color
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Star size

Events

Event	Detail	Description
`change`	`{ value: number }`	Fired when the user selects a rating

CSS Custom Properties

Property	Description
`--rating-star-size`	Size of each star icon
`--rating-color-empty`	Color of unselected stars
`--rating-color-filled`	Color of selected / hovered stars
`--rating-gap`	Gap between stars

Accessibility

The rating component follows WCAG 2.1 Level AA standards.

`bit-rating`

✅ Keyboard Navigation

← / → arrow keys move and commit the selection.
Home / End jump to 1 / max; Tab moves focus in and out.

✅ Screen Readers

The group uses role="radiogroup"; each star uses role="radio" with aria-checked reflecting the current selection.
aria-labelledby links the group label.
aria-disabled reflects the disabled state; aria-readonly reflects the readonly state.
Hover previews stars visually without committing the value.

Best Practices

Do:

Always provide a label attribute so screen readers announce the context (e.g. "Product rating").
Use readonly rather than disabled when showing an existing score that the user cannot change — readonly keeps the element accessible in the reading order.
Use colour together with label text to reinforce meaning (e.g. color="warning" for a gold star aesthetic).

Don't:

Use rating for non-numeric preference input — a bit-select or bit-radio-group conveys options more clearly.
Omit the label attribute — an unlabelled rating group is inaccessible.

Slider — drag-based numeric value picker

Usage Guide

Framework Integration

Theming

Examples

Rating

Features

Source Code

Basic Usage

Colors

Sizes

Custom Max

Readonly

Solid Stars

Disabled

API Reference

Attributes

Events

CSS Custom Properties

Accessibility

`bit-rating`

Best Practices

Rating ​

Features ​

Source Code ​

Basic Usage ​

Colors ​

Sizes ​

Custom Max ​

Readonly ​

Solid Stars ​

Disabled ​

API Reference ​

Attributes ​

Events ​

CSS Custom Properties ​

Accessibility ​

bit-rating ​

Best Practices ​

Related Components ​

Rating

Features

Source Code

Basic Usage

Colors

Sizes

Custom Max

Readonly

Solid Stars

Disabled

API Reference

Attributes

Events

CSS Custom Properties

Accessibility

`bit-rating`

Best Practices

Related Components