RatingField
Star-rating input with configurable length, half-increment support, hover preview and clearable option.
Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-rating-field> — 5 parts: root ①, label ②, star wrapper ③, individual star item ④, and clear button ⑤.- 1.origam-rating-field
- Root element. Inline-flex container. Wraps OrigamInput for label/messages.
- 2.origam-rating-field__label
- Label zone rendered via OrigamLabel. Visible when label prop is set.
- 3.origam-rating-field__wrapper
- Per-star-position wrapper. Hosts optional itemLabel above/below the star.
- 4.origam-rating-field__content
- Inner row hosting one or two OrigamRatingFieldItem per position (two when halfIncrements=true).
- 5.origam-rating-field__clear
- Clear button (OrigamBtn icon). Visible when clearable=true and modelValue > 0.
API
Props
All props accepted by this component, with their type, default value and description.
- namestring
- Name used for the radio inputs in the star row. Auto-generated if not provided.
- labelstring
- Label rendered above the star row via OrigamLabel.
- itemAriaLabelstring
- Aria-label template for each star item. Interpolated with the item value.
- clearablebooleanfalse
- Shows a clear button when the current value > 0 and the field is not disabled or readonly.
- disabledbooleanfalse
- Disables all interaction. Hides the clear button and prevents click/hover events.
- emptyIcon
- MDI icon used for unfilled stars. Defaults to mdi-star-outline.
- fullIcon
- MDI icon used for filled (selected) stars. Defaults to mdi-star.
- halfIncrementsbooleanfalse
- Allows selection of half-star values (0.5, 1.5, 2.5…). Renders two items per star position.
- hoverbooleanfalse
- Enables hover preview: hovering a star highlights all stars up to that position.
- lengthnumber | string5
- Total number of rating items (stars). Default is 5.
- readonlybooleanfalse
- Makes the field read-only (pointer-events: none). Useful for display-only ratings.
- modelValuenumber | string0
- Current rating value. Bound with v-model. Clamped to [0, length].
- itemLabelsArray<string>
- Text labels displayed above or below each star position.
- Position of item labels: 'top' (above the star row) or 'bottom' (below).
- centerAffixboolean
- hideDetailsboolean | string
- hideSpinButtonsboolean
- hintstring
- persistentHintboolean
- messagesArray<string> | string
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- Adjusts the density of the Input wrapper.
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- roundedboolean | number | string | TRounded | null | undefined
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- colorTColor
- bgColorTColor
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- elevationTElevation
- heightnumber | string
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- directionTDirection
- errorstring | boolean
- errorMessagesArray<string> | string
- maxErrorsnumber | string
- rulesArray<any>
- validateOnTValidateOn
- validationValueany
- focusedboolean
- appendAvatarstring
- appendIconTIcon
- prependAvatarstring
- prependIconTIcon
- prependAriaLabelstring
- appendAriaLabelstring
- Controls the size of each star icon.
- fontSizeTFontSize
- fontWeightTFontWeight
- lineHeightTLineHeight
- rippleboolean | { class: string }true
- Enables ripple effect on each star item.
- tagstring'div'
- Root HTML tag. Defaults to div.
- textstring
- floatingboolean
- requiredbooleanfalse
- Marks the field as required.
- letterSpacingTLetterSpacing
API
Slots
Content slots exposed by this component.
- #default
- Replaces the entire inner layout (label + star row). Receives input context.
- #label
- Custom label content replacing the default OrigamLabel.
- #itemLabel
- Custom label content for each star position. Also supports per-index slot `itemLabel.{index}`.
- #details
- #messages
- Custom messages/errors area below the star row.
- #message
- #prepend
- Content prepended before the rating row.
- #append
- Content appended after the rating row.
API
Emits
Events emitted by this component.
- @update:modelValueany
- Emitted when the user clicks a star. Carries the new numeric rating value.
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props to sub-components.
- Ref<string>
- Reactive CSS string generated by useStyle.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the computed style sheet. Called automatically on mount.
- () => void
- Removes the injected style sheet. Called automatically on unmount.
- Ref<boolean>
- True once the style sheet has been injected.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Gap between star items.
- Transition duration for star fill animations.
- Color of unfilled star items.
- Color of filled (selected) star items.
- Icon size for each star item.
- Transform scale applied to a star on hover.
- Opacity of the entire field when disabled.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | Action |
|---|---|
| Tab | Moves focus to the first or next star item. |
| Arrow Left / Right | Navigates between star positions. |
| Space | Selects the focused star value. |
Notes
- Each star item renders a native <input type="radio">. Screen readers announce position and total (e.g. "3 of 5").
- When readonly=true, pointer-events are disabled. The read-only class is applied to the root.
- itemAriaLabel provides a custom aria-label template for each star, replacing the default numeric label.
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Basic usage
Hover preview & half increments
Custom icons
Ecosystem
Family
Components from the same folder that share conventions and often compose together.