Form Rating

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

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 the variant 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 -->

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-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:

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 or disabled 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 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 -->

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 locale resolves to a right-to-left language, the Left and Right behaviour is reversed.

Component reference

`<b-form-rating>`

v2.12.0+

View source

<b-form-rating> Component aliases
<b-form-rating> Properties
<b-form-rating> v-model
<b-form-rating> Slots
<b-form-rating> Events

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.

Properties

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`

Slots

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

Events

Event	Arguments	Description
`change`	`value` - Current ratings value	Emitted to update the v-model

Importing individual components

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)

Importing as a Vue.js plugin

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)