Rating

Demos

How to import

<script lang="ts">
    import { Rating } from '@fibrae/semi-ui-svelte';
</script>

Basic Usage

Support two sizes: default, small.

Supports customized size if pass in a number. Refer to Customize

<script lang="ts">
    import { Rating } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Rating value={5} />
    <br />
    <br />
    <Rating size="small" value={5} />
</div>

Half Star

Use allowHalf to support selection of half stars. Support to display decimals ratings other than 0.5.

<script lang="ts">
    import { Rating } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Rating allowHalf value={3.5} />
    <br />
    <Rating allowHalf disabled value={3.65} />
</div>

Disabled

Use disabled to disabled interaction.

<script lang="ts">
    import { Rating } from '@fibrae/semi-ui-svelte';
</script>

<Rating disabled value={3} />

Click to Clear

allowClear Property allows you to clear the value when you click on the component again. By default it is set to true.

<script lang="ts">
    import { Rating } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <span>允许再次点击清除</span>
    <br />
    <Rating allowClear value={3} />
    <br />
    <br />
    <span>禁止再次点击清除</span>
    <br />
    <Rating allowClear={false} value={3} />
</div>

Text Description

Use tooltips to add description to Rating.

<script lang="ts">
    import { Rating } from '@fibrae/semi-ui-svelte';

    let value = $state<number | undefined>(0);
    const desc = ['极差', '较差', '一般', '满意', '非常满意'];
</script>

<div>
    <span>
        你对获得的帮助是否满意：
        {#if value}
            <span>{desc[value - 1]}</span>
        {/if}
    </span>
    <br />
    <Rating bind:value tooltips={desc} />
</div>

Customize

You can customize characters, numbers of rating and size.

Note that customized size could only work with customized characters.

Use the character prop to customize the character: pass a string, or a snippet defined with {#snippet character()}...{/snippet}.

<script lang="ts">
    import { IconLikeHeart } from '@fibrae/semi-icons-svelte';
    import { Rating } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Rating style="color: red" value={3}>
        {#snippet character()}
            <IconLikeHeart size="extra-large" />
        {/snippet}
    </Rating>
    <br />
    <br />
    <Rating allowHalf size={48} style="color: red" value={3}>
        {#snippet character()}
            <IconLikeHeart style="font-size: 48px" />
        {/snippet}
    </Rating>
    <br />
    <br />
    <Rating character="赞" size={18} value={3} />
    <br />
    <br />
    <Rating count={10} value={6} />
</div>

API Reference

Props

Methods

value is bindable and there is no defaultValue: a plain value is the initial value, bind:value reads and writes it, and a function binding can refuse or rewrite it. class, style (a string) and native attributes (id, aria-labelledby, aria-invalid, aria-required, data-* and so on) land on the role="radiogroup" root ul; aria-label is used as the accessible name as is, and without it the name summarizes the current value; tabindex and name are discarded and the list is fixed at tabindex="-1", so only the checked radio can be reached with Tab.

focus() and blur() are called through bind:this: focus() focuses the radio that Tab reaches (the same one autofocus uses), and blur() only takes effect when focus is inside the rating.

Accessibility

ARIA

• Rating has aria-checked to indicate whether it is currently selected, aria-posinset to indicate the position in the list, and aria-setsize to indicate the length of the list.
• Semi supports custom Rating semantics
  • aria-label is used as is for the accessible name of the radiogroup;
  • If the custom character is plain text (the character prop as a string in React, a text-only #character slot in Vue), each star's name uses that text as the unit, otherwise the locale's default unit;
  • The two are independent and can be passed together.

Keyboard and Focus

• Initial focus settings for Rating (the Tab stop, following the APG radio group):
  • If there is a selection item in Rating, the initial focus is set to the last selection item (for example: if 3 stars are lit, the initial focus is set on the third lit star);
  • If Rating has no selected item (value is 0), the initial focus is on the empty-star radio that stands for 0 stars;
  • When the value matches no radio (for example 2.5 without allowHalf), the first radio is the Tab stop, so the keyboard can still enter; an arrow key then selects the adjacent radio (3 with the right arrow and 2 with the left arrow for 2.5).
• On a Rating group, use the down arrow or right arrow to select the next star (the value increases, and wraps to 0 after the last star) and the up arrow or left arrow to select the previous star (the value decreases, and wraps from 0 to the last star); in RTL only the left and right arrows are mirrored;
  • The user sets the allowHalf property, and presses the arrow keys to select or deselect only half a star;
• Space selects the focused star when it is not selected; pressing Space on a selected star does not clear it. Clear with Enter or a click (controlled by allowClear);
• The list itself is not a Tab stop, so Rating used as a Tooltip trigger adds no extra Tab stop;
• Calling focus() on the instance focuses the radio that Tab reaches;
• With tooltips, keyboard focus on a star shows that star's tip, linked through aria-describedby;
• A disabled Rating cannot get the focus.

Design Tokens