Form Rating

BootstrapVue's custom star rating component, BFormRating, is for entering or displaying a rating value. The component is fully WAI-ARIA accessible and supports keyboard control.

Edit this page on GitHub

Overview

Rating values range from 1 to the number of stars allowed (default stars is 5, minimum stars is 3). Since BFormRating uses the Bootstrap class form-control, it can easily be placed inside input groups.

There are two main modes for BFormRating: interactive and readonly.

Interactive mode allows the user to choose a rating from 1 to the number of stars (default 5) in whole number increments.

Interactive rating (input mode):

Current rating: 0

HTML

vue

<template>
  <BFormRating v-model="rating" />

  <p>Current rating: {{ rating }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'
const rating = ref(0)
</script>

Readonly mode is used for displaying an aggregated rating, and supports half stars.

Readonly (non-interactive) rating:

Current rating: 2.567

HTML

vue

<template>
  <BFormRating
    v-model="rating"
    :readonly="true"
  />

  <p>Current rating: {{ rating }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'
const rating = ref(2.567)
</script>

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.

Current rating: 3

HTML

vue

<template>
  <BFormRating
    v-model="rating"
    variant="primary"
    aria-label="Primary rating"
  />
  <BFormRating
    v-model="rating"
    variant="secondary"
    aria-label="Secondary rating"
  />
  <BFormRating
    v-model="rating"
    variant="success"
    aria-label="Success rating"
  />
  <BFormRating
    v-model="rating"
    variant="danger"
    aria-label="Danger rating"
  />
  <BFormRating
    v-model="rating"
    variant="warning"
    aria-label="Warning rating"
  />
  <BFormRating
    v-model="rating"
    variant="info"
    aria-label="Info rating"
  />
  <p>Current rating: {{ rating }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'
const rating = ref(3)
</script>

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:

Current rating: 3

HTML

vue

<template>
  <BFormRating
    v-model="rating"
    color="indigo"
  />
  <BFormRating
    v-model="rating"
    color="#ff00ff"
  />
  <BFormRating
    v-model="rating"
    color="rgb(64, 192, 128)"
  />
  <BFormRating
    v-model="rating"
    color="rgba(64, 192, 128, 0.75)"
  />

  <p>Current rating: {{ rating }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'
const rating = ref(3)
</script>

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, <BFormRating> defaults to 5 stars. You can change the number of stars via the stars prop. The minimum allowed stars is 3.

Rating with 10 stars:

Value: 0

Rating with 7 stars:

Value: 0

HTML

vue

<template>
  <label>Rating with 10 stars:</label>
  <BFormRating
    v-model="rating10"
    :stars="10"
  />
  <p>Value: {{ rating10 }}</p>

  <label>Rating with 7 stars:</label>
  <BFormRating
    v-model="rating7"
    :stars="7"
  />
  <p class="mt-2">Value: {{ rating7 }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'
const rating10 = ref(0)
const rating7 = ref(0)
</script>

Show value

By default, <BFormRating> 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.

Current rating: 4

HTML

vue

<template>
  <BFormRating
    v-model="rating"
    show-value
  />

  <p>Current rating: {{ rating }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'
const rating = ref(4)
</script>

With precision set:

3.56

Current rating: 3.555

HTML

vue

<template>
  <BFormRating
    v-model="rating"
    show-value
    :precision="2"
  />

  <p>Current rating: {{ rating }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'
const rating = ref(3.555)
</script>

Show maximum value

Optionally, show the maximum rating possible by also setting the prop show-value-max to true:

3.56/5

Current rating: 3.555

HTML

vue

<template>
  <BFormRating
    v-model="rating"
    show-value-max
    :precision="2"
  />
  <p>Current rating: {{ rating }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'
const rating = ref(3.555)
</script>

Control sizing

Fancy a small or large rating control? Simply set the prop size to either 'sm' or 'lg' respectively.

Small rating

Default rating (medium)

Large rating

Current rating: 4

HTML

vue

<template>
  <label for="rating-sm">Small rating</label>
  <BFormRating
    id="rating-sm"
    v-model="rating"
    size="sm"
  />

  <label for="rating-md">Default rating (medium)</label>
  <BFormRating
    id="rating-md"
    v-model="rating"
  />

  <label for="rating-lg">Large rating</label>
  <BFormRating
    id="rating-lg"
    v-model="rating"
    size="lg"
  />

  <p>Current rating: {{ rating }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'
const rating = ref(4)
</script>

Inline mode

By default, <BFormRating> occupies 100% width of the parent container. In some situations, you may prefer the custom input to occupy only the space required for its contents. Simply set the inline prop to true to render the component in inline mode:

Inline rating:

HTML

vue

<template>
  <label for="rating-inline">Inline rating:</label>
  <BFormRating
    id="rating-inline"
    v-model="rating"
    inline
  />
</template>

<script setup lang="ts">
import {ref} from 'vue'
const rating = ref(4)
</script>

Borderless

By default, BFormRating has standard Bootstrap form-control styling. To disable the default form-control border, simply set the no-border prop to true.

Small rating with no border

Default rating (medium) with no border

Large rating with no border

Current rating: 4

HTML

vue

<template>
  <label for="rating-sm">Small rating with no border </label>
  <BFormRating
    id="rating-sm"
    v-model="rating"
    size="sm"
    no-border
  />

  <label for="rating-md">Default rating (medium) with no border </label>
  <BFormRating
    id="rating-md"
    v-model="rating"
    no-border
  />

  <label for="rating-lg">Large rating with no border </label>
  <BFormRating
    id="rating-lg"
    v-model="rating"
    size="lg"
    no-border
  />

  <p>Current rating: {{ rating }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'
const rating = ref(4)
</script>

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:

Not yet implemented

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).

Readonly rating

3.654

HTML

vue

<template>
  <label for="rating-readonly">Readonly rating</label>
  <BFormRating
    id="rating-readonly"
    v-model="rating"
    readonly
    show-value
    :precision="3"
  />
</template>

<script setup lang="ts">
import {ref} from 'vue'
const rating = ref(3.6536)
</script>

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.

2.5

Current rating: 2.5

HTML

vue

<template>
  <BFormRating
    v-model="rating"
    show-value
    :precision="2"
    show-clear
  />

  <p>Current rating: {{ rating }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'
const rating = ref(2.5)
</script>

Notes:

The clear icon will not be shown when the props readonly or disabled are set.

Icons

By default, BFormRating uses built-in star SVG icons:

Empty star: outlined star
Half star: half-filled star
Full star: filled star
Clear button: x icon

Default icons styling

When using the default icons, you can style them with the variant, color, and size props. These props apply Bootstrap classes and styles to the built-in SVG icons.

Custom icons

To use completely custom icons, use the default scoped slot which provides access to starIndex, isFilled, and isHalf properties:

Rating: 0

HTML

vue

<template>
  <div>
    <BFormRating
      v-model="rating"
      :stars="5"
      show-value
      show-clear
    >
      <template #default="{starIndex, isFilled}">
        <!-- Full heart -->
        <svg
          v-if="isFilled"
          aria-hidden="true"
          class="custom-icon"
          width="1.5em"
          height="1.5em"
          viewBox="0 0 24 24"
          fill="currentColor"
          @click="rating = starIndex"
        >
          <path
            d="M12 4.528a6 6 0 0 0-8.243 8.715l6.829 6.828a2 2 0 0 0 2.828 0l6.829-6.828A6 6 0 0 0 12 4.528z"
            fill="currentColor"
          />
        </svg>

        <!-- Empty heart -->
        <svg
          v-else
          aria-hidden="true"
          class="custom-icon"
          width="1.5em"
          height="1.5em"
          viewBox="0 0 24 24"
          fill="none"
          stroke="currentColor"
          @click="rating = starIndex"
        >
          <path
            d="M12 4.528a6 6 0 0 0-8.243 8.715l6.829 6.828a2 2 0 0 0 2.828 0l6.829-6.828A6 6 0 0 0 12 4.528z"
          />
        </svg>
      </template>
    </BFormRating>

    <p class="mt-2">Rating: {{ rating }}</p>
  </div>
</template>

<script setup lang="ts">
import {ref} from 'vue'
import {BFormRating} from 'bootstrap-vue-next/components/BFormRating'

const rating = ref(0)
</script>

<style scoped>
.custom-icon {
  cursor: pointer;
  user-select: none;
  transition: transform 0.2s ease;
  color: #a01918;
}
.b-form-rating:not(.is-readonly) .custom-icon:hover {
  transform: scale(1.25);
}
</style>

Important notes for custom icons:

The variant, color, and size props do not apply to custom icons provided via scoped slots
You must handle all styling (colors, sizes, hover effects) yourself in your custom CSS
You're responsible for implementing click handlers if needed: @click="rating = starIndex"
Custom icons completely replace the default star rendering

Icon props (Advanced)

The icon-empty, icon-half, icon-full, and icon-clear props are available for specifying alternate Bootstrap Icon names, but require the corresponding Bootstrap Icon components to be registered. Most users should use the scoped slot approach shown above for custom icons.

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).

Not yet implemented

Using in input groups

The following is an example of placing <BFormRating> in an input group:

Not yet implemented

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.

Not yet implemented

Implementation notes

The ratings control uses the Bootstrap v5 form-control*, d-* (display), and text-{variant} classes, as well as BootstrapVue's custom CSS for proper styling.

Not yet implementedThe root element of the control is an <output> element, which allows a <label> element to be

associated with it.

Accessibility

To screen reader users <BFormRating> 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

`<BFormRating>`

View Source

<BFormRating> Properties
<BFormRating> Events
<BFormRating> Slots

Adding styles: .form‑rating

Properties

Prop	Type	Default	Description
color	`string`	`undefined`	CSS color to use instead of variant. Accepts either a HEX or RGB/RGBA string
id	`string`	`undefined`	Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
inline	`boolean`	`'false'`	When `true` renders as an inline element rather than a block (100% width) element
model-value	`number`	`0`	The current rating value (supports v-model two-way binding).
no-border	`boolean`	`'false'`	When `true`, removes the border around the rating component
precision	`number`	`undefined`	Specify the number of digits after the decimal to show. Defaults to to no defined precision
readonly	`boolean`	`'false'`	When `true` makes the rating readonly. When `true`, fractional ratings values are allowed (half icons will be shown)
show-clear	`boolean`	`'false'`	When `true`, shows a clear button to reset the rating
show-value	`boolean`	`'false'`	When `true` shows the current rating value in the control
show-value-max	`boolean`	`'false'`	When set to `true` and prop `show-value` is `true`, includes the maximum star rating possible in the formatted value
size	`'sm' \| 'lg' \| string`	`'1rem'`	Icon size: accepts CSS units (e.g. '1.5rem', '24px') or the presets 'sm' (.875rem) and 'lg' (1.25rem); defaults to 1rem.
stars	`number`	`5`	The number of stars to show. Minimum value is `3`, default is `5`
variant	`ColorVariant \| null`	`null`	Applies one of the Bootstrap theme color variants to the component. When implemented `bg-variant` and `text-variant` will take precedence

Events

Event	Args	Description
update:model-value	`value: number` - Currently selected rating value.	Emitted when the selected value(s) are changed. Looking for the `input` or `change` event - use `update:model-value` instead.

Slots

Name	Scope	Description
default	`star-index: number` - The index of the star being rendered (0-based index) `is-filled: boolean` - When `true`, the star is filled (selected) `is-half: boolean` - When `true`, the star is half-filled (partially selected)	Custom renderer for each star.

Form Rating ​

Overview ​

Styling ​

Variant and color ​

Number of stars ​

Show value ​

Show maximum value ​

Control sizing ​

Inline mode ​

Borderless ​

Disabled ​

Readonly ​

Clear button ​

Icons ​

Default icons styling ​

Custom icons ​

Icon props (Advanced) ​

Form submission ​

Using in input groups ​

Internationalization ​

Implementation notes ​

Accessibility ​

Component Reference

<BFormRating>

Properties

Events

Slots

Form Rating

Overview

Styling

Variant and color

Number of stars

Show value

Show maximum value

Control sizing

Inline mode

Borderless

Disabled

Readonly

Clear button

Icons

Default icons styling

Custom icons

Icon props (Advanced)

Form submission

Using in input groups

Internationalization

Implementation notes

Accessibility

`<BFormRating>`