Skip to content

OrigamMediaScrubber ​

<OrigamMediaScrubber> is the headless, media-agnostic "value on a track" primitive: a role="slider" widget with a full pointer-drag, keyboard and ARIA pipeline, and no state of its own. The parent owns modelValue and listens to update:modelValue.

It is used twice inside the design system — as the timeline of <OrigamMediaController> and as the (vertical) level slider of <OrigamMediaVolumeControl> — which is the whole point: one drag/keyboard implementation instead of the <input type="range"> + rotate(-90deg) hack.

Basic usage ​

vue
<template>
    <OrigamMediaScrubber
        v-model="position"
        :min="0"
        :max="duration"
        aria-label="Playback position"
    />
</template>

<script setup lang="ts">
    import { ref } from 'vue'

    const position = ref(0)
    const duration = ref(180)
</script>

Orientation ​

Horizontal is the YouTube-timeline shape; vertical is the volume / level-meter shape, where the top of the track is max and the bottom is min.

The component sizes itself off its parent — width: 100% when horizontal, height: 100% when vertical. A vertical instance in an unbounded wrapper collapses to zero height and becomes invisible, so give it a bounded height.

vue
<template>
    <div style="height: 160px">
        <OrigamMediaScrubber
            v-model="level"
            :min="0"
            :max="100"
            orientation="vertical"
            aria-label="Volume"
        />
    </div>
</template>

Buffered channel ​

buffered paints a second bar from min up to the buffered position — the browser's media buffer, in the media use case. Pass undefined to hide it entirely.

vue
<template>
    <OrigamMediaScrubber
        v-model="position"
        :min="0"
        :max="200"
        :buffered="140"
        aria-label="Playback position"
    />
</template>

Hover tooltip ​

showHoverTooltip reveals a tooltip above the cursor while it sits over the track. It is horizontal-only — the vertical variant is too narrow to anchor one cleanly; build your own outside the component if you need it.

vue
<template>
    <OrigamMediaScrubber
        v-model="position"
        :min="0"
        :max="100"
        show-hover-tooltip
        :format-hover-tooltip="(v) => `${Math.round(v)}%`"
        aria-label="Playback position"
    />
</template>

Props ​

Value & range ​

PropTypeDefaultDescription
modelValuenumber— (required)Current value, clamped into [min, max]. Supports v-model. Never mutated internally.
minnumber0Lower bound of the range.
maxnumber— (required)Upper bound. max <= min freezes the scrubber at the start.
stepnumber0Discrete step. 0 means continuous — pointer events emit the raw float.
bufferednumber | undefinedundefinedOptional buffered position. Renders the __buffer bar; undefined hides it.

Design ​

PropTypeDefaultDescription
orientationTMediaScrubberOrientation ('horizontal' | 'vertical')'horizontal'Layout axis.
colorTColorundefinedPaints the progress bar (track and buffer stay neutral by design). Tokenised values emit a utility class; custom values fall back to inline style.
roundedTRoundedundefinedTrack radius. Also accepts the per-corner roundedTopLeft / … variants via IRoundedProps.
showThumbOnHoverOnlybooleanfalseHides the thumb at rest, reveals it on hover / focus / drag — the YouTube pattern.
showHoverTooltipbooleanfalseShows a tooltip above the cursor. Horizontal only.
formatHoverTooltip(value: number) => stringvalue => String(value)Formatter for the default tooltip label. Overridden entirely by the tooltip slot.

Behaviour & a11y ​

PropTypeDefaultDescription
disabledbooleanfalseDrops role, sets tabindex="-1", and turns pointer + keyboard into no-ops.
ariaLabelstringundefinedRead by screen readers on focus. Always pass a translated string.
ariaValueTextstringundefinedHuman-readable value ("1:23", "45 %") mapped to aria-valuetext.
dataCystring'origam-media-scrubber'data-cy selector for the host. A parent-forwarded value wins over the literal fallback.

dataCy is declared as a prop, which removes it from $attrs — the template renders it explicitly. Both in-house parents forward one, so inside <OrigamMediaController> / <OrigamMediaVolumeControl> the fallback is never what renders: target the composed name (origam-media-controller-scrubber, origam-media-controller-volume) in tests, not the bare literal.

Emits ​

EmitPayloadWhen
update:modelValuenumberLive — during drag, on keyboard, and on click.
changenumberCommit — on pointerup / pointercancel after a drag, and on every keyboard change.
dragstart—pointerdown captured.
dragend—pointerup / pointercancel.
hovernumber | nullHovered value on pointermove; null on pointerleave.

Slots ​

SlotBindingsDescription
tooltip{ value: number }Hover-tooltip body. Rendered only when showHoverTooltip is true, the orientation is horizontal, and the cursor is over the track.

Accessibility ​

The host carries the full slider contract: role="slider" (dropped when disabled, so assistive tech is not invited to interact with a frozen widget), aria-orientation, aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext, aria-label and aria-disabled.

Keyboard, matching the WAI-ARIA Authoring Practices slider pattern:

KeyEffect
ArrowRight / ArrowLeft±1 step — horizontal only
ArrowUp / ArrowDown±1 step — vertical only
PageUp / PageDown±10 % of the range
Home / EndJump to min / max

The step size is step when it is > 0, otherwise 5 % of the range.

aria-valuemax reports the declared max, never the epsilon ​

The percentage math divides by max - min, which is floored by an internal epsilon (MEDIA_SCRUBBER_MIN_RANGE) so an empty range paints 0% rather than NaN%. That floor is deliberately not shared with aria-valuemax, which reports Math.max(max, min) — the value a consumer could recognise.

This matters because a frozen range is the normal mount state of a media scrubber, not an error: OrigamMediaController feeds a max of 0 until state.duration becomes finite. Folding the two quantities together leaked aria-valuemax="1e-7" to assistive tech for the whole pre-loadedmetadata window.

Reduced motion ​

Track-thickness and thumb-scale transitions are disabled under prefers-reduced-motion: reduce.

Exposed ​

defineExpose surfaces rootEl (the host element), isScrubbing and hoverValue for consumers that need to coordinate with an in-flight drag.