Rating

The <x-wirekit::rating> component displays an interactive rating control. It uses role="radiogroup" with individual radio buttons for each icon, providing full keyboard and screen reader support. The default icon is a star, but you can choose from several built-in shapes.

Basic Usage

<x-wirekit::rating label="Your rating" name="rating" />

Preselected Value

<x-wirekit::rating label="Product rating" name="product" :value="3" />

Custom Max

<x-wirekit::rating label="Score" name="score" :max="10" :value="7" />

Size Variants

<x-wirekit::rating label="Small" name="r-sm" size="sm" :value="4" />

<x-wirekit::rating label="Medium" name="r-md" size="md" :value="4" />

<x-wirekit::rating label="Large" name="r-lg" size="lg" :value="4" />

Readonly

<x-wirekit::rating label="Average rating" name="avg" :value="4" :readonly="true" />

In readonly mode the rating is a record of a score, not a control that happens to be switched off — so it renders as a picture: role="img" with one accessible name ("4 out of 5 stars"), nothing focusable inside it, and no form field.

That last part matters more than it sounds. A display-only rating used to emit a hidden input with a generated name, so a page showing 24 product ratings shipped 24 stray form fields that a surrounding <form> would submit.

Pass aria-label when "4 out of 5 stars" does not say enough on its own — with several ratings on a page, none of them says what scored 4:

<x-wirekit::rating :value="4.2" readonly aria-label="Average customer rating" />

An interactive rating is unchanged: it is a real radiogroup, because picking a score is choosing one of five.

Fractional Stars

Readonly mode supports fractional values for displaying average ratings:

<x-wirekit::rating label="3.78 average" name="frac1" :value="3.78" :readonly="true" />

<x-wirekit::rating label="4.5 stars" name="frac2" :value="4.5" :readonly="true" />

<x-wirekit::rating label="2.2 stars" name="frac3" :value="2.2" :readonly="true" />

Fractional values only work in readonly mode. Interactive ratings always snap to whole icons.

Icon Shapes

The icon prop lets you swap stars for other shapes. All shapes support interactive mode, readonly mode, fractional fill, and all size variants.

<x-wirekit::stack gap="md">
    <x-wirekit::rating label="Star (default)" name="i-star" icon="star" :value="4" />
    <x-wirekit::rating label="Heart" name="i-heart" icon="heart" :value="4" />
    <x-wirekit::rating label="Circle" name="i-circle" icon="circle" :value="4" />
    <x-wirekit::rating label="Square" name="i-square" icon="square" :value="4" />
    <x-wirekit::rating label="Diamond" name="i-diamond" icon="diamond" :value="4" />
    <x-wirekit::rating label="Thumb" name="i-thumb" icon="thumb" :value="4" />
</x-wirekit::stack>

Fractional Icons

Custom icons also support fractional fill in readonly mode:

<x-wirekit::rating label="Love score" name="love" icon="heart" :value="3.7" :readonly="true" />

Custom Colors

The filled icon color uses the --color-wk-warning token because amber/yellow is the universal standard color for star ratings (Amazon, Google, IMDb, etc.). The token's name refers to its semantic role in the design system (warning notifications), but the amber hue happens to be the perfect match for rating icons.

You can recolor ratings per instance by overriding --color-wk-warning with any value — including other WireKit tokens:

<x-wirekit::stack gap="md">
    <x-wirekit::rating label="Default (amber)" name="c-default" :value="4" :readonly="true" />
    <x-wirekit::rating label="Red hearts" name="c-red" icon="heart" :value="4" :readonly="true" style="--color-wk-warning: #e11d48;" />
    <x-wirekit::rating label="Blue stars" name="c-blue" :value="4" :readonly="true" style="--color-wk-warning: #2563eb;" />
    <x-wirekit::rating label="Green circles" name="c-green" icon="circle" :value="4" :readonly="true" style="--color-wk-warning: #16a34a;" />
</x-wirekit::stack>

You can also reference other design tokens instead of hardcoded hex values:

{{-- Use the accent color (indigo by default) --}}
<x-wirekit::rating name="r" :value="4" style="--color-wk-warning: var(--color-wk-accent);" />

{{-- Use the success color (green) --}}
<x-wirekit::rating name="r" icon="circle" :value="3" style="--color-wk-warning: var(--color-wk-success);" />

{{-- Use the danger color (red) for hearts --}}
<x-wirekit::rating name="r" icon="heart" :value="5" style="--color-wk-warning: var(--color-wk-danger);" />

This way your ratings stay consistent with your theme — when you change your accent or success color, the ratings update automatically.

To change the color globally, override --color-wk-warning in your theme. For per-scope customization, use the scope prop with personalization:

// config/wirekit.php — personalize a specific scope
'personalizations' => [
    'rating' => [
        'love-meter' => [
            'base' => '[--color-wk-warning:#e11d48]',
        ],
    ],
],

<x-wirekit::rating scope="love-meter" icon="heart" name="love" :value="4" />

Width & Layout

The rating component auto-sizes to its number of icons and the size prop. It does not stretch to fill its container — it has a natural inline width based on max × icon size.

Form Submission

A hidden <input type="hidden"> submits the numeric rating value under the given name.

Livewire Integration

<x-wirekit::rating> keeps its current rating in internal state seeded from the value prop, so when binding with Livewire pass the bound property as :value alongside wire:model to seed the initial rating:

<x-wirekit::rating wire:model.live="score" :value="$score" />

Without :value the control shows 0 stars until the user picks a rating; wire:model keeps it in sync afterward. This is the framework-agnostic seeding pattern WireKit's stateful controls share — it works in plain Blade forms too.

Optimistic UI

Pass the name of the Livewire method the rating should call and the new score appears immediately, then confirms or undoes itself when the server answers:

<x-wirekit::rating
    name="score"
    label="Score"
    :value="$score"
    optimistic="rate"
/>

Load wirekit-optimistic.js alongside whichever bundle you already use — below it, in your layout:

@wirekitScripts
<script src="{{ asset('vendor/wirekit/wirekit-optimistic.js') }}"></script>

Try it

The demo below runs the real path: the change shows immediately, the outline says it is provisional, and the server's answer either confirms it silently or takes it back.

{{-- In your app there is no host: your own Livewire component owns the method. --}}
<x-wirekit::rating
    name="score"
    label="Score"
    :value="$score"
    optimistic="rate"
/>

The <livewire:demos.…> wrapper above exists only on this site — it supplies the demo methods so the page can show a real round trip. The block under it is what you write.

The prop takes a method name rather than true because the component cannot know the action otherwise: server actions reach a WireKit component through the attribute bag, so it never sees your wire:click. optimistic replaces wire:model.live here rather than joining it — the method you name is what changes the score on the server; pass the current one with :value so the rating knows where it started.

A second pick while one is in flight is refused rather than queued. Queued, the final score would depend on which answer arrived last — network timing, which is both wrong and impossible to test.

The hidden form field follows both the optimistic write and the undo, so a plain HTML form never submits a score that was taken back.

Readonly ratings ignore the prop. A readonly rating is a picture of a score with nothing to operate, so there is no action to anticipate.

Scope. This covers mutations: changing something and showing it right away. Sorting, filtering and pagination are query round trips — nobody can show a result nobody knows yet — and are deliberately not covered.

Props

Accessibility

• Outer container: role="radiogroup" with aria-label from the label prop
• Each star: visually hidden <input type="radio"> with aria-label="N of M stars"
• Selected state communicated via native radio checked attribute
• Star SVGs are aria-hidden="true" — the radio input provides the accessible name
• Hover preview shows which rating would be selected (visual-only, no AT announcement)
• Readonly mode sets aria-readonly="true" on the radiogroup
• Live region announces the selected value on change: "N of M stars"

Keyboard Interaction

The component uses roving tabindex — only the currently selected star (or the first star if none selected) is in the tab order.

Pitfalls

• Don't use rating as a single-value display. Reach for stars with readonly if the value is read-only — but for narrative copy "Rated 4.2/5" is more screen-reader-friendly than a five-star widget.

Design Tokens

Customization

Override defaults in config/wirekit.php:

'components' => [
    'rating' => ['max' => 5, 'size' => 'md'],
],

Further Reading

• WAI-ARIA: Radiogroup Pattern
• MDN: role="radiogroup"
• MDN: role="radio"
• MDN: aria-readonly
• MDN: Roving tabindex