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
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<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.
- modelValuerequirednumber—
- 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.
- maxrequirednumber—
- 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
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: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
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
Keyboard interactions
| Key | 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.
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.
- 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).
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
Vertical volume slider