RatingFieldItem
Individual star item in a RatingField. Renders an icon-only Btn in text variant that handles filled/hovered/half-increment state and a visually-hidden radio input.
Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-rating-field-item> — 4 parts. Root ① wraps the visually-hidden accessible label ② and the star Btn ③ (with fullIcon/emptyIcon). A hidden radio input ④ tracks the selection state for screen readers and form submission.- 1.origam-rating-field-item
- Root element (div by default). Applies --half / --full modifier classes when halfIncrements is active.
- 2.origam-rating-field-item__hidden (label)
- Visually-hidden inside a
- 3.origam-btn (variant="text" icon)
- Inner OrigamBtn rendered in variant="text" icon mode. Displays fullIcon or emptyIcon depending on filled/hovered state. The #item slot overrides this.
- 4.origam-rating-field-item__hidden (input)
- Visually-hidden native (tabindex="-1"). Tracks checked state for form participation and screen reader state. Not focusable — keyboard navigation uses the Btn.
API
Props
All props accepted by this component, with their type, default value and description.
- namestring
- Name attribute used to build the id of the hidden radio input (id = "{name}-{value}").
- indexnumber-1
- Zero-based position of this item in the parent RatingField.
- valuerequirednumber—
- Numeric value this star represents (e.g. 1, 1.5, 2, …). Required.
- labelstring
- Accessible label for this star. Falls back to the itemAriaLabel locale key.
- itemAriaLabelstring
- showStarbooleantrue
- When false, the OrigamBtn icon is hidden (half-increment placeholder).
- isFilledbooleanfalse
- True when this star is within the current rating value (shows fullIcon).
- isHoveredbooleanfalse
- True when the cursor is over this star or a later star (triggers hover preview).
- isHoveringbooleanfalse
- True when the parent RatingField is in a hover state. Controls whether isFilled or isHovered drives the icon selection.
- disabledbooleanfalse
- Disables the star button and the hidden radio input.
- readonlybooleanfalse
- Makes the star non-interactive without disabling it visually.
- MDI icon shown when the star is filled (isFilled=true or isHovered=true).
- MDI icon shown when the star is empty.
- halfIncrementsbooleanfalse
- Enables half-star rendering. When true, items with fractional values apply clip-path to show only half the star.
- checkedbooleanfalse
- Checked state of the underlying hidden radio input.
- lengthnumber | string
- Total number of stars in the parent RatingField. Used to build the accessible label.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- tagstring'div'
- Root HTML element rendered by the component.
- color
- Icon color. Overrides the default star fill color from the rating-field token.
- density
- Density passed down from the parent RatingField.
- rippleboolean | { class: string }true
- Enables the Material ripple on the star button.
- size
- Size of the inner Btn / icon. Propagated from the parent RatingField.
- 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
- 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
- elevationTElevation
API
Slots
Content slots exposed by this component.
- #item
- Replaces the default OrigamBtn star with a custom element. Receives all computed btn props and the numeric value.
API
Emits
Events emitted by this component.
- @mouseenterMouseEvent
- Fired when the pointer enters this star. Used by the parent to drive hover preview.
- @mouseleaveMouseEvent
- Fired when the pointer leaves this star. Used by the parent to clear hover preview.
- @changeEvent
- @keydownKeyboardEvent
- @clickMouseEvent
- Fired when the star button is clicked. Forwarded from the inner OrigamBtn.
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 child components.
- Ref<string>
- Reactive CSS string generated by useStyle.
- ComputedRef<string>
- Computed id of the hidden radio input ("{name}-{value}").
- () => 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.
- string
- Unique style-sheet ID for this instance.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Default (empty) star color.
- Star color when filled or hovered.
- Star color when disabled.
- Icon size of each star.
- Scale applied to the star on hover.
- Transition duration for scale and color animations.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | Action |
|---|---|
| Tab | Focuses the star button. The hidden radio input is tabindex="-1" and not directly reachable by Tab. |
| Space / Enter | Activates the star button, emitting click and setting the parent RatingField value. |
Notes
- The hidden radio input is always present but tabindex="-1". It participates in form submission and screen-reader state announcements without entering the normal keyboard focus order.
- The accessible label (aria text) is built from the itemAriaLabel locale key via t(itemAriaLabel, value, length). It reads "Rate N of M stars" for screen readers.
- In half-increment mode, items with value % 1 > 0 use clip-path to show half a star. Both the full and half items render a separate label/input pair so the underlying model remains accessible.
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.
Standalone (internal usage)
Custom item slot via RatingField
Ecosystem
Family
Components from the same folder that share conventions and often compose together.