Functionality for videos that minimize ("dock") to a corner or a custom position on scroll.
<script async custom-element="amp-video-docking" src="https://cdn.ampproject.org/v0/amp-video-docking-0.1.js"></script>
amp-video-docking component allows videos to be minimized to a corner or
to a custom positioned element via the
If this attribute is present and the video is playing manually, the video will be "docked" and float on a corner or a custom position when the user scrolls out of the video component's visual area. If the user scrolls back, the video reverts to its original static position.
- The video can be docked to a default corner or to a custom fixed position.
- The video can be dragged and repositioned by the user on a different corner.
- The video can be flicked to be dismissed from its docked position.
- Multiple videos on the same page can be docked, but only one at a time will be docked and fixed.
This extension is used in conjunction with a supported video player. Currently, the supported players are:
Note that the video won't be docked unless it's playing manually. This means:
- If the video has
autoplay, the feature will not be triggered unless the user clicks on the video first.
- If the video does not have
autoplay, the feature will not be triggered unless the user plays the video.
- If the video is paused while scrolling, it will not be docked.
On scroll, the video will minimize to an automatically calculated corner or to a custom defined position.
When setting the
dock attribute with an empty value, the video will dock to a corner defined by the extension:
<amp-video src="my-video.mp4" ... dock></amp-video>
By default, the video will be minimized to the top-right corner. It will be sized at 30% of the viewport's width, no less than 180 pixels wide. If the document is RTL, the video will dock to the top-left corner. When in this mode, users can drag the docked video to snap to either corner.
Custom position by "slot"
When setting the
dock attribute to a non-empty value, the video will dock to the same position as a "slot element" referenced in the attribute value by CSS selector.
<amp-layout id="my-dock-slot" ...> <amp-video src="my-video.mp4" ... dock="#my-dock-slot"></amp-video ></amp-layout>
In order for custom positioning to work properly, the slot element must be
Custom positioning will be rejected when the element target is not visible. This means that corner targets or slot elements can be picked depending on layout by CSS media queries. For an example where target types are combined and applied in different layout conditions, see AMP by Example.
amp-video-docking does not define any custom elements. To use this extension, set the
dock attribute on
an elligible video player component.
When the video becomes docked or undocked by scrolling, the low-trust events
undock are triggered respectively.
These can, for example, trigger an
amp-animation that slides content in order to make room for the docked element. For an example where events trigger animations required for docking, see AMP by Example.
Depending on the docking target, the corresponding event will be triggered from different source elements:
- From the video element itself, when the video is docked to a corner.
- From the slot element, when the video is docked to the slot element.
You can set
undock action triggers on either the video or the slot to alter your layout differently when combining target types.
The docked video can be styled by selecting elements that are created by this extension.
References a layer that draws a
box-shadow under the video. The shadow can be
overridden or removed. Its opacity will change from 0 to 1 while the video is
References a layer that contains the docked video controls. Usually, this
doesn't need to be styled. See
.amp-docked-video-controls-bg for a background
This element also gets the classname
amp-small applied when rendered in small areas (those under 300 pixels wide), and the classname
amp-large when not.
References a layer that draws an overlay background over the video and under the controls. It's displayed only when the controls are displayed. Its background can be overridden or removed.
A controls group that contains a set of buttons. Only one of these elements are displayed at a time depending on the state of the video:
The playback set is displayed on most scenarios and contains play/pause, mute/unmute and fullscreen buttons.
The scroll back set only contains a button to scroll the document back to the video's inline position. This is displayed during ad playback in order to allow user interaction.
The dismiss button is not part of a controls set and is always displayed.
A button "group" that usually contains two buttons, with only one displayed at
a time. It's used to draw a background when the button is active. It has a
border-radius and a
background-color set by default, both of which can be
removed or overrridden.
Direct children (
.amp-docked-video-button-group > [role=button]) represent
buttons, which have an SVG background. The color of the SVG can be changed by
fill property. Additionally, these can be replaced by changing
Represents a button to scroll the document back to the video's inline position during ad playback to allow user interaction.
This button is different from the other control buttons in that the
amp-large classnames on the
do not affect it. Because it's the only button in its set, it's also larger than
the others, at 64 by 64 pixels. Other control buttons are sized at 40 by 40
The icon for this button (set through the
background-image CSS property)
changes depending on the relative direction of the docked area. When the video
docks from left-to-right, the
.amp-docked-video-controls container gets no
additional classnames, but it will get the
amp-rtl classname when the video
docks in the opposite direction. This allows the button to be drawn with an
arrow pointing in the correct direction.
Represents a container for placeholder elements placed on the empty component area.
Represents a layer displaying the
placeholder image of the video on the empty component area. Blurred by default.
Represents an animated icon for a UX affordance displayed on the empty component area.
This element also gets the classname
amp-small when rendered in small viewports (those under 420 pixels wide). It also gets the classname
amp-rtl when animating from right to left.
See amp-video-docking rules in the AMP validator specification.