README.md
Form Rating
BootstrapVue's custom star rating component,
<b-form-rating>
, is for entering or displaying a rating value. The component is fully WAI-ARIA accessible and supports keyboard control.
Overview
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 -->
Styling
Variant and color
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:
- The prop
color
takes precedence over thevariant
prop - Variants translate to the
text-{variant}
utility class on the icon
Number of stars
By 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 -->
Show value
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 -->
Show maximum value
2.13.0+
Optionally show the maximum rating possible by also setting the prop show-value-max
to true
:
<template>
<div>
<b-form-rating
v-model="value"
readonly
show-value
show-value-max
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-max.vue -->
Control sizing
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 -->
Inline mode
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 -->
Borderless
By default, <b-form-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:
- For accessibility reasons a focus ring will show when the rating component has focus, regardless
of the
no-border
setting.
Disabled
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
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 -->
Clear button
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:
- The clear icon will not be shown when the props
readonly
ordisabled
are set.
Icons
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.
Form submission
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).
Using in input groups
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 -->
Internationalization
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 preferred 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 -->
Implementation notes
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.
Accessibility
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:
- Left or Down will decrement the rating value by
1
- Right or Up will increment the rating value by
1
- When the <code>locale</code> resolves to a right-to-left language, the Left and Right behaviour is reversed.