Component aliases
<b-form-rating>
can also be used via the following aliases:
<b-rating>
Note: component aliases are only available when importing all of BootstrapVue or using the component group plugin.
BootstrapVue's custom range component, <b-form-rating>
, is for entering or displaying a rating value. The component is fully WAI-ARIA accessible and supports keyboard control.
Available in BootstrapVue since v2.12.0
Rating values range from 1
to the number of stars allowed (default stars is 5
, minimum stars is 3
). Since <b-form-rating>
uses the Bootstrap class form-control
, it can easily be placed inside input groups.
There are two main modes for <b-form-rating>
: interactive and readonly.
Interactive mode allows the user to chose a rating from 1
to the number of stars (default 5
) in whole number increments.
Interactive rating (input mode):
<template>
<div>
<b-form-rating v-model="value"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: null
}
}
}
</script>
<!-- b-form-rating.vue -->
Readonly mode is used for displaying an aggregated rating, and supports half
stars.
Readonly (non-interactive) rating:
<template>
<div>
<b-form-rating v-model="value" readonly></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: 2.567
}
}
}
</script>
<!-- b-form-rating-non-interactive.vue -->
Easily apply one of the Bootstrap theme color variants to the rating icon via the variant
prop. The default is to use the default form control text color.
<template>
<div>
<b-form-rating v-model="value" variant="warning" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" variant="success" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" variant="danger" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" variant="primary" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" variant="info" class="mb-2"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: 3
}
}
}
</script>
<!-- b-form-rating-variant.vue -->
To apply a custom color, use the color
prop which accepts a standard CSS color name, HEX color value (#...
) or RGB/RGBA (rgb(...)
/rgba(...)
) color value:
<template>
<div>
<b-form-rating v-model="value" color="indigo" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" color="#ff00ff" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" color="rgb(64, 192, 128)" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" color="rgba(64, 192, 128, 0.75)" class="mb-2"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: null
}
}
}
</script>
<!-- b-form-rating-color.vue -->
Notes:
color
takes precedence over the variant
proptext-{variant}
utility class on the iconBy default, <b-form-rating>
defaults to 5
stars. You can change the number of stars via the stars
prop. The minimum allowed stars is 3
.
<template>
<div>
<label for="rating-10">Rating with 10 stars:</label>
<b-form-rating id="rating-10" v-model="value10" stars="10"></b-form-rating>
<p class="mt-2">Value: {{ value10 }}</p>
<label for="rating-7">Rating with 7 stars:</label>
<b-form-rating id="rating-7" v-model="value7" stars="7"></b-form-rating>
<p class="mt-2">Value: {{ value7 }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value10: null,
value7: null,
}
}
}
</script>
<!-- b-form-rating-stars.vue -->
By default <b-form-rating>
does not display the current numerical value. To show the current value simply set the show-value
prop to true
. To control the precision (number of digits after the decimal) simply set the precision
prop to the number of digits after the decimal to show. The precision
setting is useful when showing an aggregated or average rating value in readonly
mode.
<template>
<div>
<b-form-rating v-model="value" show-value></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: 4
}
}
}
</script>
<!-- b-form-rating-value.vue -->
With precision set:
<template>
<div>
<b-form-rating v-model="value" readonly show-value precision="2"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: 3.555
}
}
}
</script>
<!-- b-form-rating-value-precision.vue -->
Fancy a small or large rating control? Simply set the prop size
to either 'sm'
or 'lg'
respectively.
<template>
<div>
<label for="rating-sm">Small rating</label>
<b-form-rating id="rating-sm" v-model="value" size="sm"></b-form-rating>
<label for="rating-md" class="mt-3">Default rating (medium)</label>
<b-form-rating id="rating-md" v-model="value"></b-form-rating>
<label for="rating-lg" class="mt-3">Large rating</label>
<b-form-rating id="rating-lg" v-model="value" size="lg"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: null
}
}
}
</script>
<!-- b-form-rating-size.vue -->
By default, <b-form-rating>
occupies 100% width of the parent container. In some situations you may prefer the custom input to occupy on the space required for it's contents. Simply set the inline
prop to true
to render the component in inline mode:
<template>
<div>
<label for="rating-inline">Inline rating:</label>
<b-form-rating id="rating-inline" inline value="4"></b-form-rating>
</div>
</template>
<!-- b-form-rating-inline.vue -->
By default, <b-from-rating>
has standard Bootstrap form-control styling. To disable the default form-control border, simply set the no-border
prop to true
.
<template>
<div>
<label for="rating-sm-no-border">Small rating with no border</label>
<b-form-rating id="rating-sm-no-border" v-model="value" no-border size="sm"></b-form-rating>
<label for="rating-md-no-border" class="mt-3">Default rating (medium) with no border</label>
<b-form-rating id="rating-md-no-border" v-model="value" no-border></b-form-rating>
<label for="rating-lg-no-border" class="mt-3">Large rating with no border</label>
<b-form-rating id="rating-lg-no-border" v-model="value" no-border size="lg"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: null
}
}
}
</script>
<!-- b-form-rating-no-border.vue -->
Notes:
no-border
setting.If you require additional information before a user can chose a ratings value, simply set the disabled
prop to true
to disable any user interactivity on the component:
<template>
<div>
<label for="rating-disabled">Disabled rating</label>
<b-form-rating id="rating-disabled" value="2.75" disabled></b-form-rating>
</div>
</template>
<!-- b-form-rating-disabled.vue -->
Readonly ratings remain focusable, but are not interactive. This state is useful for displaying an aggregated or average ratings value. Fractional values are allowed and will result in the displaying of half icons when the value
is not a whole number (the half icon threshold is 0.5
).
<template>
<div>
<label for="rating-readonly">Readonly rating</label>
<b-form-rating
id="rating-readonly"
value="3.6536"
readonly
show-value
precision="3"
></b-form-rating>
</div>
</template>
<!-- b-form-rating-readonly.vue -->
Optionally show a clear icon via the show-clear
prop. The value will be set to null
when the clear icon is clicked.
<template>
<div>
<b-form-rating v-model="value" show-clear show-value></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: 2.5
}
}
}
</script>
<!-- b-form-rating-clear.vue -->
Notes:
readonly
or disabled
are set.By default <b-form-rating>
uses the Bootstrap Icons icons 'star'
, 'star-half'
, 'star-fill'
, and the icon 'x'
(for the optional clear button). You can specify alternate Bootstrap Icons to use via the icon-empty
, icon-half
, icon-full
, and icon-clear
props. These props accept a Bootstrap Icon kebab-case name, and requires that the corresponding icon component be registered/installed either locally or globally.
<template>
<div>
<b-form-rating
icon-empty="heart"
icon-half="heart-half"
icon-full="heart-fill"
icon-clear="slash-circle"
show-clear
variant="danger"
><b-form-rating>
</div>
</template>
<!-- b-form-rating-icons.vue -->
Alternatively, you an supply your own content via the 'icon-empty'
, 'icon-half'
, 'icon-full'
, and 'icon-clear'
scoped slots.
If you intend to submit the rating value via standard form submission, set the name
prop to the desired form field name. A hidden input will be generated with the current value (or an empty string if there is no value).
The following is an example of placing <b-form-rating>
in an input group:
<template>
<div>
<b-input-group>
<b-input-group-prepend>
<b-button @click="value = null">Clear</b-button>
</b-input-group-prepend>
<b-form-rating v-model="value" color="#ff8800"></b-form-rating>
<b-input-group-append>
<b-input-group-text class="justify-content-center" style="min-width: 3em;">
{{ value }}
</b-input-group-text>
</b-input-group-append>
</b-input-group>
</div>
</template>
<script>
export default {
data() {
return {
value: null
}
}
}
</script>
<!-- b-form-rating-input-group.vue -->
When a locale
is specified, the displayed value (when the show-value
prop is true
) will be in the browser's default locale. To change the locale, simple set the locale
prop to the preferred locale, or an array of prefered locales (most preferred locale first). This will affect the optional displayed value and the left-to-right or right-to-left orientation of the component.
<template>
<div>
<b-form-select v-model="locale" :options="locales" class="mb-2"></b-form-select>
<b-form-rating v-model="value" :locale="locale" show-value precision="1"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: 3.5,
locale: 'en-US',
locales: [
{ text: 'English US (en-US)', value: 'en-US' },
{ text: 'French (fr)', value: 'fr' },
{ text: 'Persian (fa)', value: 'fa'},
{ text: 'Arabic Egyptian (ar-EG)', value: 'ar-EG' }
]
}
}
}
</script>
<!-- b-form-rating-i18n.vue -->
The ratings control uses the Bootstrap v4 form-control*
, d-*
(display), border-*
and text-{variant}
classes, as well as BootstrapVue's custom CSS for proper styling.
The root element of the control is an <output>
element, which allows a <label>
element to be associated with it.
To screen reader users <b-form-rating>
appears as a slider type input input.
Keyboard navigation is employed to select the rating value, and mimics the keyboard controls of range
inputs:
1
1
locale
resolves to a right-to-left language, the Left and Right behaviour is reversed.<b-form-rating>
Component aliases
<b-form-rating>
Properties
<b-form-rating>
v-model
<b-form-rating>
Slots
<b-form-rating>
Events
<b-form-rating>
can also be used via the following aliases:
<b-rating>
Note: component aliases are only available when importing all of BootstrapVue or using the component group plugin.
Property (Click to sort Ascending) | Type | Default | Description |
---|---|---|---|
id | String | Used to set the 'id' attribute on the rendered content, and used as the base to generate any additional element IDs as needed | |
value v-model | Number or String | null | Rating value. This is the v-model |
stars | Number or String | 5 | The number of stars to show. Minimum value is `3`, default is `5` |
variant Settings | String | null | Applies one of the Bootstrap theme color variants to the component |
color Settings | String | null | CSS color to use instead of variant. Accepts either a HEX or RGB/RGBA string |
show-value | Boolean | false | When `true` shows the current rating value in the control |
disabled | Boolean | false | When set to 'true', disables the component's functionality and places it in a disabled state |
readonly | Boolean | false | When `true` makes the rating readonly. When `true`, fractional ratings values are allowed (half icons will be shown) |
size | String | Set the size of the component's appearance. 'sm', 'md' (default), or 'lg' | |
name | String | Sets the value of the 'name' attribute on the form control | |
form | String | ID of the form that the form control belongs to. Sets the 'form' attribute on the control | |
no-border | Boolean | false | When `true` disables the default border |
inline | Boolean | false | When `true` renders as an inline element rather than a blick (100% width) element |
precision | Number or String | null | Specify the number of digits after the decimal to show. Defaults to to no defined precision |
icon-empty | String | 'star' | Bootstrap Icon name to use for the empty icon. Note icon must be registered in your component or globally |
icon-half | String | 'star-half' | Bootstrap Icon name to use for the half icon. Note icon must be registered in your component or globally |
icon-full | String | 'star-fill' | Bootstrap Icon name to use for the full icon. Note icon must be registered in your component or globally |
icon-clear | String | 'x' | Bootstrap Icon name to use for the clear button. Note icon must be registered in your component or globally |
locale | String or Array | Locale (or locales) to use when showing the value when prop `show-value` is set. Defaults to the browser default locale | |
show-clear | Boolean | false | When `true` shows the clear value icon button |
v-model
Property | Event |
---|---|
value | change |
Slot Name | Scoped | Description |
---|---|---|
icon-empty | Content for the empty icon | |
icon-half | Content for the half icon | |
icon-full | Content for the full icon | |
icon-clear | No | Content for the optional clear button |
Event | Arguments | Description |
---|---|---|
change |
| Emitted to update the v-model |
You can import individual components into your project via the following named exports:
Component | Named Export | Import Path |
---|---|---|
<b-form-rating> | BFormRating | bootstrap-vue |
Example:
import { BFormRating } from 'bootstrap-vue' Vue.component('b-form-rating', BFormRating)
This plugin includes all of the above listed individual components. Plugins also include any component aliases.
Named Export | Import Path |
---|---|
FormRatingPlugin | bootstrap-vue |
Example:
import { FormRatingPlugin } from 'bootstrap-vue' Vue.use(FormRatingPlugin)