MediaScrubber

Media
stable

Headless media-agnostic track-and-thumb slider widget. Owns the full pointer-events drag pipeline, keyboard matrix (ARIA slider pattern), optional buffer bar, hover tooltip and both horizontal and vertical orientations. Used internally by OrigamMediaController for the timeline and the volume slider.

Structure

Anatomie

Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.

Anatomy of OrigamMediaScrubberSchematic of the horizontal scrubber with 5 numbered parts: root, track, buffer bar, progress bar, thumb and hover tooltip. 0:48 1 2 3 4 5 6 ① root — ② track — ③ buffer bar — ④ progress bar — ⑤ thumb — ⑥ hover tooltip
Anatomy of <origam-media-scrubber> — 6 internal parts. Root ①, track ② (full-width bg), optional buffer bar ③, progress bar ④ (fills to modelValue %), draggable thumb ⑤, and the hover tooltip ⑥ (horizontal only, conditional on showHoverTooltip).
1.origam-media-scrubber
Root div. role="slider" (or undefined when disabled), tabindex="0" (or -1 when disabled), aria-orientation, aria-valuemin/max/now/text, aria-label. Handles all pointer and keyboard events. position: relative; cursor: pointer; touch-action: none; user-select: none.
2.origam-media-scrubber__track
Track bar. Background color from token --origam-media-scrubber---track-bg. Height grows from --track-thickness to --track-thickness-active on hover / focus / scrubbing. aria-hidden="true".
3.origam-media-scrubber__buffer
Buffered portion bar. Renders from min to buffered%. Background --origam-media-scrubber---buffer-bg. Visible only when buffered prop is a finite number. aria-hidden="true".
4.origam-media-scrubber__progress
Playback progress bar. Width/height = valuePct%. Background --origam-media-scrubber---primary. aria-hidden="true".
5.origam-media-scrubber__thumb
Circular drag handle. Position driven by valuePct% (left in horizontal, bottom in vertical). Hidden at rest when showThumbOnHoverOnly=true; revealed on :hover, :focus-visible and .origam-media-scrubber--scrubbing. aria-hidden="true".
6.origam-media-scrubber__hover-tooltip
Hover tooltip. position: absolute; bottom: calc(100% + 8px); left = hoverPct%. Contains the #tooltip slot or the formatted value string. Horizontal orientation only. aria-hidden="true".

API

Props

Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.

modelValue
requis
number
—
Current value between min and max. Supports v-model. The component never mutates this directly — every change surfaces via update:modelValue.
min
number
0
Lower bound of the value range.
max
requis
number
—
Upper bound of the value range. Required to compute the thumb position. Passing 0 or any value <= min freezes the scrubber at the start.
step
number
0
Discrete step. 0 (default) means continuous — pointer events emit the raw float; positive values snap each emission to the nearest multiple.
buffered
number
Optional buffered position (end of the browser's media buffer). Renders the __buffer bar from min up to buffered. Pass undefined to hide the bar entirely.
orientation
TMediaScrubberOrientation
'horizontal'
Layout axis. horizontal = YouTube timeline shape; vertical = volume / level meter shape (top of track = max, bottom = min).
disabled
boolean
false
Disables pointer + keyboard interaction. The element drops out of the tab order (tabindex="-1") and pointer events become no-ops.
showThumbOnHoverOnly
boolean
false
Hides the thumb at rest and reveals it on hover / focus / drag — the YouTube pattern. When false, the thumb is always visible.
showHoverTooltip
boolean
false
Shows a tooltip above the cursor (horizontal only) reflecting the hovered value. Content can be overridden via the #tooltip slot.
formatHoverTooltip
(value: number) => string
value => String(value)
Formatter for the default hover tooltip label. Receives the hovered value, returns the string to render.
ariaLabel
string
—
Required accessibility label read by screen readers when the scrubber gains focus. Always pass a translated string here.
ariaValueText
string
Optional human-readable representation of the current value (e.g. "1:23" for a timestamp, "45 %" for a volume level). Mapped to aria-valuetext.
dataCy
string
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
color
Intent or custom color applied to the track background via useBackgroundColor. Utility class emitted for tokenised values; inline style for custom colors.
Border-radius token for the track element. Applied via useRounded.
roundedTopRight
boolean | number | string
roundedTopLeft
boolean | number | string
roundedBottomLeft
boolean | number | string
roundedBottomRight
boolean | number | string
roundedStartStart
boolean | number | string
roundedStartEnd
boolean | number | string
roundedEndStart
boolean | number | string
roundedEndEnd
boolean | number | string

API

Slots

Emplacements de contenu exposés par ce composant.

#tooltip
Hover-tooltip body. Receives the hovered value. Only rendered when showHoverTooltip=true and orientation="horizontal" and the cursor sits over the track.

API

Emits

Événements émis par ce composant.

@update:modelValue
number
Live value update — fires during drag, keyboard and click. The parent should update modelValue immediately for smooth thumb tracking.
@change
number
Commit event — fires on pointerup or pointercancel after a drag, and on keyboard arrow/home/end. Signals that the user has finished adjusting the value.
@dragstart
void
Fired when pointer capture starts (pointerdown). Useful to pause video thumbnail generation or lock the parent UI during scrubbing.
@dragend
void
Fired when the drag ends (pointerup or pointercancel).
@hover
number | null
Fires with the hovered value on pointermove, and with null on pointerleave. Useful for updating a preview thumbnail or a secondary tooltip outside the scrubber.

API

Membres exposés

Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.

Ref<HTMLElement | null>
Template ref to the root DOM element. Useful for measuring the track dimensions or programming pointer capture externally.
Ref<boolean>
True while a pointer drag is captured. The parent can use this to suppress autohide logic on the controller overlay during a drag.
Ref<number | null>
The hovered track value while the cursor is over the scrubber. null when the cursor has left. Mirrors the hover emit.

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.

Primary accent color. Drives --origam-media-scrubber---primary (progress bar + thumb fill).
Idle track fill. Semi-transparent by design (overlaid on the media surface).
Buffer bar fill. Slightly more opaque than the track.
Diameter of the circular thumb handle.
Track thickness at rest.
Track thickness on hover / focus / scrubbing. Animates over 140ms.
Hover tooltip background. Near-black for contrast.
Hover tooltip text color.

Inclusion

Accessibilité

Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.

Rôles ARIA

slider

Interactions clavier

Interactions clavier
ToucheAction
ArrowRight / ArrowUpIncreases the value by step (or 5% of range when step=0). ArrowRight for horizontal; ArrowUp for vertical.
ArrowLeft / ArrowDownDecreases the value by step (or 5% of range when step=0). ArrowLeft for horizontal; ArrowDown for vertical.
PageUpIncreases the value by 10% of the range (same regardless of step).
PageDownDecreases the value by 10% of the range.
HomeSets the value to min.
EndSets the value to max.

Notes

  • role="slider" is set only when not disabled. When disabled, the role attribute is omitted (undefined) and tabindex becomes -1 so AT users are not invited to interact with a frozen widget.
  • ariaLabel is a required prop. Always pass a translated string (e.g. "Seek" for the timeline, "Volume" for the volume slider). The label must describe the purpose of the slider, not its current value.
  • Use ariaValueText for a human-readable representation of the value — e.g. "1:23" for a timestamp so screen readers announce "1 minute 23 seconds" rather than the raw float "83.4".
  • Under prefers-reduced-motion: reduce, both track and thumb CSS transitions are disabled (transition: none).
  • The component uses setPointerCapture() on pointerdown so drag events continue even when the pointer leaves the element boundary. This is the standard drag pattern for range inputs on touch devices.

Fondation

Design tokens

Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.

Source
color
var(--origam-color__action--primary---bg)
Primary color (progress bar + thumb fill).
dimension
12px
Circular thumb diameter.
color
var(--origam-color__neutral---900)
Hover tooltip background (near-black for contrast).
color
var(--origam-color__neutral---0)
Hover tooltip text color (white).

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.

Video timeline scrubber

vue

Vertical volume slider

vue