MediaScrubber
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.
<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.
- modelValuerequisnumber—
- Current value between min and max. Supports v-model. The component never mutates this directly — every change surfaces via update:modelValue.
- minnumber0
- Lower bound of the value range.
- maxrequisnumber—
- Upper bound of the value range. Required to compute the thumb position. Passing 0 or any value <= min freezes the scrubber at the start.
- stepnumber0
- Discrete step. 0 (default) means continuous — pointer events emit the raw float; positive values snap each emission to the nearest multiple.
- bufferednumber
- 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.
- orientationTMediaScrubberOrientation'horizontal'
- Layout axis. horizontal = YouTube timeline shape; vertical = volume / level meter shape (top of track = max, bottom = min).
- disabledbooleanfalse
- Disables pointer + keyboard interaction. The element drops out of the tab order (tabindex="-1") and pointer events become no-ops.
- showThumbOnHoverOnlybooleanfalse
- Hides the thumb at rest and reveals it on hover / focus / drag — the YouTube pattern. When false, the thumb is always visible.
- showHoverTooltipbooleanfalse
- Shows a tooltip above the cursor (horizontal only) reflecting the hovered value. Content can be overridden via the #tooltip slot.
- formatHoverTooltip(value: number) => stringvalue => String(value)
- Formatter for the default hover tooltip label. Receives the hovered value, returns the string to render.
- ariaLabelstring—
- Required accessibility label read by screen readers when the scrubber gains focus. Always pass a translated string here.
- ariaValueTextstring
- Optional human-readable representation of the current value (e.g. "1:23" for a timestamp, "45 %" for a volume level). Mapped to aria-valuetext.
- dataCystring
- idstring
- classstring | Array<string> | object
- stylestring | 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.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | 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:modelValuenumber
- Live value update — fires during drag, keyboard and click. The parent should update modelValue immediately for smooth thumb tracking.
- @changenumber
- 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.
- @dragstartvoid
- Fired when pointer capture starts (pointerdown). Useful to pause video thumbnail generation or lock the parent UI during scrubbing.
- @dragendvoid
- Fired when the drag ends (pointerup or pointercancel).
- @hovernumber | 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
Interactions clavier
| Touche | Action |
|---|---|
| ArrowRight / ArrowUp | Increases the value by step (or 5% of range when step=0). ArrowRight for horizontal; ArrowUp for vertical. |
| ArrowLeft / ArrowDown | Decreases the value by step (or 5% of range when step=0). ArrowLeft for horizontal; ArrowDown for vertical. |
| PageUp | Increases the value by 10% of the range (same regardless of step). |
| PageDown | Decreases the value by 10% of the range. |
| Home | Sets the value to min. |
| End | Sets 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.
- colorvar(--origam-color__action--primary---bg)
- Primary color (progress bar + thumb fill).
- dimension12px
- Circular thumb diameter.
- colorvar(--origam-color__neutral---900)
- Hover tooltip background (near-black for contrast).
- colorvar(--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
Vertical volume slider