To source

Atrium // Elements

a-media

Unstyled control elements for native audio and video elements.

The a-media-* elements are unstyled controls for a native <audio> or <video> element. Place the media element and any controls inside an <a-media> container. The controls read the state of the media element and update on its media events, no player library is needed. They are used by the Audio and Video components.

ElementDescription
a-mediaContainer. Controls inside of it control its <audio> or <video> element.
a-media-playToggles playback. Slots play and pause.
a-media-muteToggles mute. Slots mute and unmute.
a-media-skipSkips by seconds, negative values skip backward.
a-media-rateCycles through playback rates and renders the current rate.
a-media-timeDisplays the current, duration or remaining time.
a-media-seekSeek slider, extends a-range.
a-media-volumeVolume slider, extends a-range.

Accessibility

  • Buttons: The button elements get role="button" and are focusable. They activate on click, Enter and Space. The accessible name comes from the slotted content, so include text (visually hidden if needed).
  • Sliders: Seek and volume have role="slider" and a readable aria-valuetext, like "1
    of 9
    " or "50%". Name them with the label attribute.
  • Keyboard: On the seek slider ←/→ seek by key-step seconds (default 5), Home/End jump to the start or end. On the volume slider the arrow keys change the volume by key-step (default 0.1).
  • Disabled state: a-media-skip gets aria-disabled="true" and the seek slider is disabled while the duration is unknown.
  • Volume: a-media-volume is hidden on platforms that don't allow changing the volume, like iOS. Muting still works there.
  • Group: Give the <a-media> container role="group" and an aria-label, so the controls are announced together.

Usage

import "@atrium-ui/elements/media";
<a-media role="group" aria-label="Episode 12">
  <audio src="episode.mp3" preload="metadata"></audio>

  <a-media-play>
    <span slot="play">Play</span>
    <span slot="pause">Pause</span>
  </a-media-play>

  <a-media-skip seconds="-15">Back 15 seconds</a-media-skip>
  <a-media-skip seconds="30">Forward 30 seconds</a-media-skip>

  <a-media-time type="current"></a-media-time> / <a-media-time type="duration"></a-media-time>

  <a-media-seek label="Seek"></a-media-seek>

  <a-media-rate rates="[1, 1.5, 2]">
    <span class="sr-only">Playback speed</span>
  </a-media-rate>

  <a-media-mute>
    <span slot="mute">Mute</span>
    <span slot="unmute">Unmute</span>
  </a-media-mute>

  <a-media-volume label="Volume"></a-media-volume>
</a-media>

Video

The same controls work with a <video>. For fullscreen, gestures, hotkeys or auto hiding controls, combine them with a Video.js player, like the Video component does.

<a-media>
  <video src="video.mp4" playsinline></video>

  <a-media-play>
    <span slot="play">Play</span>
    <span slot="pause">Pause</span>
  </a-media-play>

  <a-media-seek label="Seek"></a-media-seek>
</a-media>

Customization

  • Container: <a-media> has no styles of its own, it is an inline element by default.
  • Buttons: Style the elements directly, they are the buttons. Use the slots to swap icons per state.
  • Sliders: Seek and volume use the a-range custom properties and parts. The seek slider shows the buffered part of the media from the current time, styled with --range-buffer-background or ::part(buffer).
  • Time and rate: a-media-time renders plain text with tabular numbers, a-media-rate renders the rate as text like 1.5×.

MediaElement

Container for an

or

element and its controls. Controls placed anywhere inside of it control the first media element.

Example


<a-media>
  <audio src="episode.mp3" preload="metadata"></audio>
  <a-media-play>
    <span slot="play">Play</span>
    <span slot="pause">Pause</span>
  </a-media-play>
</a-media>

MediaPlayElement

Toggles playback. Shows the "play" slot while paused and the "pause" slot while playing.

Example


<a-media-play>
  <span slot="play">Play</span>
  <span slot="pause">Pause</span>
</a-media-play>

Attributes


Name Type Default value Description

MediaMuteElement

Toggles mute. Shows the "mute" slot while audible and the "unmute" slot while muted.

Example


<a-media-mute>
  <span slot="mute">Mute</span>
  <span slot="unmute">Unmute</span>
</a-media-mute>

Attributes


Name Type Default value Description

MediaSkipElement

Skips forward or backward by a number of seconds. Disabled while the duration is unknown.

Example


<a-media-skip seconds="-15">Back 15 seconds</a-media-skip>
<a-media-skip seconds="30">Forward 30 seconds</a-media-skip>

Attributes


Name Type Default value Description
seconds undefined undefined

Seconds to skip, negative values skip backward.

MediaRateElement

Cycles through playback rates. Renders the current rate, like "1.5×", after the slotted content.

Example


<a-media-rate rates="[1, 1.5, 2]">
  <span class="sr-only">Playback speed</span>
</a-media-rate>

Attributes


Name Type Default value Description
rates undefined undefined

Playback rates to cycle through.

MediaTimeElement

Displays the current time, duration or remaining time of the media.

Example


<a-media-time type="current"></a-media-time> / <a-media-time type="duration"></a-media-time>

Attributes


Name Type Default value Description
type undefined undefined

Which time to display.

MediaSeekElement

Seek slider for the media timeline. The value is the progress from 0 to 1, the buffer shows how far the media is loaded from the current time. Styled like

through its css custom properties and parts.

Example


<a-media-seek label="Seek"></a-media-seek>

Attributes


Name Type Default value Description
buffer undefined undefined

Secondary progress from 0 to 1 behind the value, like the buffered part of a video.

disabled undefined undefined

Disabled state of the range.

keyStep undefined undefined

Seconds to seek with the arrow keys.

label undefined undefined

Accessible label of the slider.

max undefined undefined

Maximum value of the range.

min undefined undefined

Minimum value of the range.

step undefined undefined

Step value of the range.

value undefined undefined

The current value of the range.

MediaVolumeElement

Volume slider from 0 to 1. Shows 0 while muted and unmutes when changed. Hidden on platforms that don't allow changing the volume, like iOS. Styled like

through its css custom properties and parts.

Example


<a-media-volume label="Volume"></a-media-volume>

Attributes


Name Type Default value Description
buffer undefined undefined

Secondary progress from 0 to 1 behind the value, like the buffered part of a video.

disabled undefined undefined

Disabled state of the range.

keyStep undefined undefined

Volume change with the arrow keys.

label undefined undefined

Accessible label of the slider.

max undefined undefined

Maximum value of the range.

min undefined undefined

Minimum value of the range.

step undefined undefined

Step value of the range.

value undefined undefined

The current value of the range.

References