# Bootstrap 5 Rating
> The Rating component allows users to provide feedback on content or services by selecting a rating value. It is customizable, supports various sizes and icons, and can be made interactive or read-only.
## How to use Rating Component.
Embed the Rating component in your HTML by using a `div` with `data-coreui-toggle="rating"`. Set the initial value with `data-coreui-value`.
```html
```
## Allow clear
Enable users to clear their selected rating by clicking on the current rating again. This functionality is activated by setting `data-coreui-allow-clear="true"`.
```html
```
This allows the selected rating to be deselected, effectively resetting the rating to a state where no value is selected.
## Resettable
Our Bootstrap Rating component allows users to assign and reset a star rating within a user interface. In the example below, we use the `button` to clear the selected value.
```html
```
## Readonly
Set the Rating component to read-only by adding `data-coreui-read-only="true"`. This disables interaction, preventing users from changing the displayed rating value.
```html
```
## Disabled
Add the `data-coreui-disabled="true"` boolean attribute to give it a grayed out appearance, remove pointer events, and prevent focusing.
```html
```
## Precision
Adjust the granularity of the Rating component by setting `data-coreui-precision`. This attribute allows for fractional ratings, such as quarter values, to provide more precise feedback.
```html
```
## Number of items
Control the total number of rating items displayed by using `data-coreui-item-count`. You can create a Rating component with a custom scale, be it larger for detailed assessments or smaller for simplicity.
```html
```
```html
```
## Tooltips
Enable descriptive text on hover by setting `data-coreui-tooltips` to `true`. This provides immediate feedback or guidance as the user interacts with the rating items.
```html
```
For custom messages, provide a comma-separated list of tooltips corresponding to each rating value to enhance the user's understanding of each rating level.
```html
```
## Sizes
Larger or smaller rating component? Add `data-coreui-size="lg"` or `data-coreui-size="sm"` for additional sizes.
```html
```
## Custom icons
Customize the Rating component with your choice of SVG icons by assigning new values to the `activeIcon` and `icon` properties in the JavaScript options. This allows for a unique look tailored to the design language of your site or application.
The Rating component can be customized with either SVG or font icons, allowing for visual alignment with your application's design. You can specify different icons for each rating value to enhance user interaction.
In the example below, we demonstrate how to set custom icons using SVG, allowing for detailed customization of the visual elements within the Rating component.
```html
```
```js
const myRatingCustomIcons1 = document.getElementById('myRatingCustomIcons1')
const optionsCustomIcons1 = {
activeIcon: '',
icon: '',
value: 3
}
new coreui.Rating(myRatingCustomIcons1, optionsCustomIcons1)
```
In the example below, we use font icons from the CoreUI Icons set. In the `activeIcon` configuration, we also apply the utility class `text-danger` to change the icon's color to red when it is active.
```html
```
```js
const myRatingCustomIcons2 = document.getElementById('myRatingCustomIcons2')
const optionsCustomIcons2 = {
activeIcon: '',
icon: '',
value: 3
}
new coreui.Rating(myRatingCustomIcons2, optionsCustomIcons2)
```
For a more dynamic experience, define different icons for each rating value, enhancing the visual feedback:
```html
```
```js
const myRatingCustomIcons3 = document.getElementById('myRatingCustomIcons3')
const optionsCustomIcons3 = {
activeIcon: {
1: '',
2: '',
3: '',
4: '',
5: ''
},
icon: {
1: '',
2: '',
3: '',
4: '',
5: ''
},
highlightOnlySelected: true,
tooltips: ['Very bad', 'Bad', 'Meh', 'Good', 'Very good'],
value: 3
}
new coreui.Rating(myRatingCustomIcons3, optionsCustomIcons3)
```
## Custom feedback
The Bootstrap Rating component integrates interactive star ratings with dynamic textual feedback using other components from CoreUI. It enables users to select a rating that updates the display and label in real-time, enhancing the interactive experience. Hover effects provide immediate feedback on potential ratings before selection, ensuring an intuitive user interface.
```html
3 / 5
Meh
```
```js
const myRatingCustomFeedback = document.getElementById('myRatingCustomFeedback')
const myRatingCustomFeedbackStart = document.getElementById('myRatingCustomFeedbackStart')
const myRatingCustomFeedbackEnd = document.getElementById('myRatingCustomFeedbackEnd')
let currentValue = 3
const labels = {
1: 'Very bad',
2: 'Bad',
3: 'Meh',
4: 'Good',
5: 'Very good'
}
const optionsCustomFeedback = {
value: currentValue
}
new coreui.Rating(myRatingCustomFeedback, optionsCustomFeedback)
myRatingCustomFeedback.addEventListener('change.coreui.rating', event => {
currentValue = event.value
myRatingCustomFeedbackStart.innerHTML = `${event.value} / 5`
myRatingCustomFeedbackEnd.innerHTML = labels[event.value]
})
myRatingCustomFeedback.addEventListener('hover.coreui.rating', event => {
myRatingCustomFeedbackEnd.innerHTML = event.value ? labels[event.value] : labels[currentValue]
})
```
## Usage
### Via data attributes
Add `data-coreui-toggle="rating"` to a `div` element.
```html
```
### Via JavaScript
Call the rating component via JavaScript:
```html
```
```js
const ratingElementList = Array.prototype.slice.call(document.querySelectorAll('.rating'))
const ratingList = ratingElementList.map(ratingEl => {
return new coreui.Rating(ratingEl)
})
```
### Options
Options can be passed using data attributes or JavaScript. To do this, append an option name to `data-coreui-`, such as `data-coreui-animation="{value}"`. Remember to convert the case of the option name from "_camelCase_" to "_kebab-case_" when using data attributes. For instance, you should write `data-coreui-custom-class="beautifier"` rather than `data-coreui-customClass="beautifier"`.
Starting with CoreUI 4.2.6, all components support an **experimental** reserved data attribute named `data-coreui-config`, which can contain simple component configurations as a JSON string. If an element has attributes `data-coreui-config='{"delay":50, "title":689}'` and `data-coreui-title="Custom Title"`, then the final value for `title` will be `Custom Title`, as the standard data attributes will take precedence over values specified in `data-coreui-config`. Moreover, existing data attributes can also hold JSON values like `data-coreui-delay='{"show":50, "hide":250}'`.
> Note that for security reasons the `sanitize`, `sanitizeFn`, and `allowList` options cannot be supplied using data attributes.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `activeIcon` | object, string, null | `null` | The default icon to display when the item is selected. |
| `allowClear` | boolean | `false` | Enables the clearing upon clicking the selected item again. |
| `allowList` | object | [Default value](https://coreui.io/bootstrap/docs/getting-started/javascript/#sanitizer) | Object which contains allowed attributes and tags. |
| `disabled` | boolean | `false` | Toggle the disabled state for the component. |
| `highlightOnlySelected` | boolean | `false` | If enabled, only the currently selected icon will be visibly highlighted. |
| `icon` | object, string, null | `null` | The default icon to display when the item is not selected. |
| `itemCount` | number | `5` | The maximum value the user can select. |
| `name` | string | `null` | The name attribute of the radio input elements. |
| `precision` | number | `1` | Minimum increment value change allowed. |
| `readOnly` | boolean | `false` | Toggle the readonly state for the component. |
| `size` | `'sm'`, `'lg'` | `null` | Size the component small or large. |
| `tooltips` | array, boolean, object | `false` | Enable tooltips with default values or set specific labels for each icon. |
| `value` | number, null | `null` | The default `value` of component. |
| `sanitize` | boolean | `true` | Enable or disable the sanitization. If activated `activeIcon`, and `icon` options will be sanitized. |
| `sanitizeFn` | null, function | `null` | Here you can supply your own sanitize function. This can be useful if you prefer to use a dedicated library to perform sanitization. |
### Methods
| Method | Description |
| --- | --- |
| `update` | Updates the configuration of the rating. |
| `reset` | Reset the value to `null` or to provided value. |
| `dispose` | Destroys a component. (Removes stored data on the DOM element) |
| `getInstance` | Static method which allows you to get the rating instance associated to a DOM element, you can use it like this: `coreui.Rating.getInstance(element)` |
| `getOrCreateInstance` | Static method which returns a rating instance associated to a DOM element or create a new one in case it wasn't initialized. You can use it like this: `coreui.Rating.getOrCreateInstance(element)` |
### Events
| Method | Description |
| --- | --- |
| `change.coreui.rating` | The callback fired when the selected item changed. |
| `hover.coreui.rating` | The callback fired when the cursor entered and leave the item. |
```js
const myRating = document.getElementById('myRating')
myRating.addEventListener('change.coreui.rating', event => {
// do something...
})
```
## Customizing
### CSS variables
Ratings use local CSS variables on `.rating` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
```scss
--cui-rating-gap: #{$rating-gap};
--cui-rating-transition: #{$rating-transition};
--cui-rating-item-height: #{$rating-item-height};
--cui-rating-item-color: #{$rating-item-color};
--cui-rating-item-scale-transform: #{$rating-item-scale-transform};
--cui-rating-item-active-color: #{$rating-item-active-color};
--cui-rating-item-icon: #{escape-svg($rating-item-icon)};
```
### SASS variables
```scss
$rating-gap: .0625rem !default;
$rating-transition: color .15s ease-out, transform .15s ease-out !default;
$rating-item-height-sm: 1rem !default;
$rating-item-height: 1.25rem !default;
$rating-item-height-lg: 1.5rem !default;
$rating-item-color: var(--cui-tertiary-color) !default;
$rating-item-scale-transform: scale(1.2) !default;
$rating-item-active-color: var(--cui-warning) !default;
$rating-item-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 512 512'%3E%3Cpath fill='currentColor' d='M470.935,194.043,333.8,171.757,270.227,48.22a16,16,0,0,0-28.454,0L178.2,171.757,41.065,194.043A16,16,0,0,0,32.273,221.1l97.845,98.636L108.936,457.051a16,16,0,0,0,23.02,16.724L256,411.2l124.044,62.576a16,16,0,0,0,23.02-16.724L381.882,319.74,479.727,221.1A16,16,0,0,0,470.935,194.043Z'%3E%3C/path%3E%3C/svg%3E") !default;
```