@douyinfe/semi-ui
Version:
A modern, comprehensive, flexible design system and UI library. Connect DesignOps & DevOps. Quickly build beautiful React apps. Maintained by Douyin-fe team.
193 lines (157 loc) • 8.05 kB
Markdown
---
localeCode: en-US
order: 45
category: Input
title: Rating
subTitle: Rating
icon: doc-rating
brief: Ratings provide insight regarding others’ opinions and experiences with a product.
---
```jsx import
import { Rating } from '@douyinfe/semi-ui';
```
Support two sizes: `default`, `small`.
Supports customized size if pass in a number. Refer to [Customize](
```jsx live=true
import React from 'react';
import { Rating } from '@douyinfe/semi-ui';
() => (
<div>
<Rating Default Value={5} />
<br />
<br />
<Rating size="small" defaultValue={5} />
</div>
);
```
Use `allowHalf` to support selection of half stars. Support to **display** decimals ratings other than 0.5.
```jsx live=true
import React from 'react';
import { Rating } from '@douyinfe/semi-ui';
() => (
<div>
<Rating allowHalf defaultValue={3.5} />
<br />
<Rating allowHalf defaultValue={3.65} disabled/>
</div>
);
```
Use `disabled` to disabled interaction.
```jsx live=true
import React from 'react';
import { Rating } from '@douyinfe/semi-ui';
() => (
<Rating disabled defaultValue={3} />
);
```
`allowClear` Property allows you to clear the value when you click on the component again. By default it is set to `true`.
```jsx live=true
import React from 'react';
import { Rating } from '@douyinfe/semi-ui';
() => (
<div>
<span>Clear when clicking</span>
<br />
<Rating allowClear={true} defaultValue={3} />
<br />
<br />
<span>Unable to clear when clicking</span>
<br />
<Rating allowClear={false} defaultValue={3} />
</div>
);
```
Use `tooltips` to add description to Rating.
```jsx live=true
import React, { useState } from 'react';
import { Rating } from '@douyinfe/semi-ui';
() => {
const [value, setValue] = useState(0);
const desc = ['terrible', 'bad', 'normal', 'good', 'wonderful'];
const handleChange = (val) => {
setValue(val);
};
return (
<div>
<span>
How was the help you received:
{value ? <span>{desc[value - 1]}</span> : ''}
</span>
<br />
<Rating tooltips={desc} onChange={handleChange} value={value} />
</div>
);
};
```
You can customize characters, numbers of rating and size.
> Note that customized size could only work with customized characters.
```jsx live=true
import React from 'react';
import { Rating } from '@douyinfe/semi-ui';
import { IconLikeHeart } from '@douyinfe/semi-icons';
() => (
<div>
<Rating style={{ color: 'red' }} character={<IconLikeHeart size="extra-large" />} defaultValue={3} />
<br />
<br />
<Rating
style={{ color: 'red' }}
size={48}
allowHalf
character={<IconLikeHeart style={{ fontSize: 48 }} />}
defaultValue={3}
/>
<br />
<br />
<Rating size={18} character={'S'} defaultValue={3} />
<br />
<br />
<Rating Count={10} defaultValue={6} />
</div>
);
```
| Properties | Instructions | type | Default |
| ------------- | ------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------- |
| allowClear | Toggle whether it is allowed to clear when clicking | boolean | true |
| allowHalf | Toggle whether it is allowed to select half stars | boolean | false |
| autoFocus | Automatically focus | boolean | false |
| character | Custom characters to display rating | React Node | `<IconStar size="extra-large"/>` |
| className | Class name | string | - |
| count | Number of stars or characters | number | 5 |
| defaultValue | Default value | number | 0 |
| disabled | Read-only, disable interaction. | boolean | false |
| preventScroll | Indicates whether the browser should scroll the document to display the newly focused element, acting on the focus method inside the component, excluding the component passed in by the user | boolean | | |
| size | Size, one of `default`, `small`, could use number for customized size | string\| number | `default` |
| style | Inline style | object | - |
| tooltips | Customize prompted information for each item | String[] | - |
| value | Controlled value | number | - |
| onBlur | Callback function when losing focus. | function() | - |
| onChange | Callback function at the time of selection | function(value: number) | - |
| onFocus | Callback function when getting focus | function() | - |
| onHoverChange | Callback function of numerical changes when the mouse hovers | function(value: number) | - |
| onKeyDown | Callback function when key down | function(e: event) | - |
- 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
- Users can use `aria-label` to customize the semantics of Rating;
- If the type of `character` passed in by the user is string, this string will be used for the semantics of Rating;
- `aria-label` has higher priority than string type `character`.
- Initial focus settings for Rating:
- If there is a selection item in Rating, the initial focus should be set to the last selection item (for example: if 3 🌟 are lit, the initial focus is set on the third lit 🌟);
- If there is no option for Rating, the initial focus should be on the entire Rating.
- On a Rating group, you can use the `right arrow` or `up arrow` to select the next focus item of the current focus, and the `left arrow` or `down arrow` to select the previous focus item of the current focus;
- The user sets the `allowHalf` property, and presses the arrow keys to select or deselect only half a star;
- A disabled Rating cannot get the focus.
<DesignToken/>