Rating

Demos

How to import

<script setup lang="ts">
    import { Rating } from '@fibrous/semi-ui-vue';
</script>

Basic Usage

Support two sizes: default, small.

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

<script setup lang="ts">
    import { Rating } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <Rating :defaultValue="5" />
        <br />
        <br />
        <Rating :defaultValue="5" size="small" />
    </div>
</template>

Half Star

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

<script setup lang="ts">
    import { Rating } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <Rating allowHalf :defaultValue="3.5" />
        <br />
        <Rating allowHalf :defaultValue="3.65" disabled />
    </div>
</template>

Disabled

Use disabled to disabled interaction.

<script setup lang="ts">
    import { Rating } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Rating :defaultValue="3" disabled />
</template>

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 setup lang="ts">
    import { Rating } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <span>允许再次点击清除</span>
        <br />
        <Rating allowClear :defaultValue="3" />
        <br />
        <br />
        <span>禁止再次点击清除</span>
        <br />
        <Rating :allowClear="false" :defaultValue="3" />
    </div>
</template>

Text Description

Use tooltips to add description to Rating.

<script setup lang="ts">
    import { ref } from 'vue';
    import { Rating } from '@fibrous/semi-ui-vue';

    const value = ref(0);
    const desc = ['极差', '较差', '一般', '满意', '非常满意'];
</script>

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

Customize

You can customize characters, numbers of rating and size.

Note that customized size could only work with customized characters.

Use the #character slot to customize the character.

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

<template>
    <div>
        <Rating :defaultValue="3" :style="{ color: 'red' }">
            <template #character>
                <IconLikeHeart size="extra-large" />
            </template>
        </Rating>
        <br />
        <br />
        <Rating allowHalf :defaultValue="3" :size="48" :style="{ color: 'red' }">
            <template #character>
                <IconLikeHeart :style="{ fontSize: '48px' }" />
            </template>
        </Rating>
        <br />
        <br />
        <Rating :defaultValue="3" :size="18">
            <template #character>赞</template>
        </Rating>
        <br />
        <br />
        <Rating :count="10" :defaultValue="6" />
    </div>
</template>

API Reference

Props

Events

Slots

Exposes

class, style and native attributes (id, aria-labelledby, aria-invalid, aria-required, data-* and so on) land on the role="radiogroup" root element through attrs. tabindex and name are discarded and the list is fixed at tabindex="-1", so only the checked radio can be reached with Tab. Once click is declared as an event, @click is no longer a native click listener on the root element.

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