RatingField
Star-rating input with configurable length, half-increment support, hover preview and clearable option.
Structure
Anatomie
Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.
<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
Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et 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
Emplacements de contenu exposés par ce composant.
- #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
Événements émis par ce composant.
- @update:modelValueany
- Emitted when the user clicks a star. Carries the new numeric rating value.
API
Membres exposés
Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.
- <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.
Personnalisation
Variables CSS
Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.
- 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
Accessibilité
Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.
Rôles ARIA
Interactions clavier
| Touche | 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.
Interactif
Playground
Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.
Rendu de l’aperçu en cours…
Usage
Exemples
Extraits de code prêts à coller dans vos templates.
Basic usage
Hover preview & half increments
Custom icons
Écosystème
Famille
Composants du même dossier qui partagent les conventions et se composent souvent ensemble.