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

Anatomy

Visual breakdown of the component's internal structure with BEM class call-outs.

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

All props accepted by this component, with their type, default value and description.

modelValue
required
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
required
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

Content slots exposed by this component.

#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

Events emitted by this component.

@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

Exposed members

Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.

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.

Customisation

CSS variables

CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.

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

Accessibility

ARIA roles, keyboard navigation and focus management. Sourced from the real component template.

ARIA roles

slider

Keyboard interactions

Keyboard interactions
KeyAction
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.

Foundation

Design tokens

Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.

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).

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.

Video timeline scrubber

vue

Vertical volume slider

vue