Version: 5.x

vm-embed

Embeds an external media player and enables interacting with it via postMessage. This is generally used internally by other providers, but you could use it if your requirements are simple. You'll also get the benefits of preconnections and lazy-loading. Refer to existing providers to see what params you can pass in, how to send commands to the player, and how to listen to events.

Usage#

<vm-embed
embed-src="https://www.youtube-nocookie.com/embed/DyTCOwB0DVw"
params="autoplay=1&muted=1&controls=0"
media-title="Agent 327: Operation Barbershop"
origin="https://www.youtube-nocookie.com"
/>
<script>
const embed = document.querySelector('vm-embed');
embed.addEventListener('vmEmbedMessage', (e) => {
const message = e.detail;
// ...
});
</script>

Properties#

PropertyDescriptionTypeDefault
decoderA function which accepts the raw message received from the embedded media player via postMessage and converts it into a POJO.((data: string) => Record<string, any> ∣ undefined) ∣ undefinedundefined
embedSrcA URL that will load the external player and media (Eg: https://www.youtube.com/embed/DyTCOwB0DVw).string''
mediaTitleThe title of the current media so it can be set on the inner iframe for screen readers.string''
originWhere the src request had originated from without any path information.string ∣ undefinedundefined
paramsThe parameters to pass to the embedded player which are appended to the embedSrc prop. These can be passed in as a query string or object.string ∣ { [x: string]: any; }''
preconnectionsA collection of URLs to that the browser should immediately start establishing a connection with.string[][]

Methods#

MethodDescriptionSignature
postMessagePosts a message to the embedded media player.postMessage(message: any, target?: string ∣ undefined) => Promise<void>

Events#

EventDescriptionType
vmEmbedLoadedEmitted when the embedded player and any new media has loaded.CustomEvent<void>
vmEmbedMessageEmitted when a new message is received from the embedded player via postMessage.CustomEvent<any>
vmEmbedSrcChangeEmitted when the embedSrc or params props change. The payload contains the params serialized into a query string and appended to embedSrc.CustomEvent<string>

Dependencies#

Used by#