Skip to Content
🎉 Coral x Panda has been released 🎉 Read the Migration Guide
DocumentationAtomsMediaPlayer

MediaPlayer

This component allows a consumer to play audio or video embeds from the following services: YouTube, Vimeo, SoundCloud and Spotify.

Basic Usage

import { MediaPlayer } from '@krakentech/coral';
 
<MediaPlayer url="https://www.youtube.com/watch?v=hJ17RoZgwfk" />
Play on YouTube

(or allow optional cookies to play it right here)

Services

YouTube

<MediaPlayer url="https://www.youtube.com/watch?v=hJ17RoZgwfk" />
Play on YouTube

(or allow optional cookies to play it right here)

Vimeo

<MediaPlayer url="https://vimeo.com/578586673" />
Play on Vimeo

(or allow optional cookies to play it right here)

SoundCloud

<MediaPlayer url="https://soundcloud.com/octopusenergy/ep-16-how-kraken-is-powering-a-transformation-at-octopus-and-beyond" />
Play on SoundCloud

(or allow optional cookies to play it right here)

Spotify

<MediaPlayer url="https://open.spotify.com/episode/1DNK1CyWKkvxmxpbiPvQGe" />
Play on Spotify

(or allow optional cookies to play it right here)

Unsupported

If an unsupported URL is given, the component will render the following message to warn of the issue.

<MediaPlayer url="https://player-widget.mixcloud.com/widget/iframe/?hide_cover=1&mini=1&feed=%2Fdublab%2Fel-marchante-tizita-radio-071524%2F" />

MediaPlayer: Unsupported platform. Youtube, Vimeo and SoundCloud and Spotify are the platforms currently supported. Please provide a URL from one of those services to the "url" prop.

Properties

title

<MediaPlayer
    url="https://www.youtube.com/embed/shT9-qX_y-w"
    title="The title of the video."
/>
Play on YouTube

(or allow optional cookies to play it right here)

aspectRatio

<MediaPlayer
    url="https://www.youtube.com/embed/shT9-qX_y-w"
    aspectRatio="9/16"
/>
Play on YouTube

(or allow optional cookies to play it right here)

cookieKeyRequiredForConsent

A string that matches the granular cookie key used across your site. For example if the user can select granular cookies like “Marketing and Social Media”, you’ll need to provide the same key value for that cookie here: “marketing_and_social_media” to allow the media to be played on your site.

The CookiePreferences organism will automatically publish an event when the user accepts or rejects cookies, even granular ones, and the MediaPlayer will automatically subscribe to this event and either render the media or not depending on the user’s selection.

<MediaPlayer
    url="https://www.youtube.com/embed/shT9-qX_y-w"
    cookieKeyRequiredForConsent="marketing_and_social_media"
/>

placeholderTitle

A string that will be used as the title of the placeholder when the media is not played because the cookies have not been accepted. The {platformName} placeholder will be replaced with the name of the platform in use (YouTube, Vimeo, SoundCloud, Spotify).

<MediaPlayer
    url="https://www.youtube.com/embed/shT9-qX_y-w"
    placeholderTitle="Play this on {platformName}"
/>

placeholderSubtitle

A string that will be used as the subtitle of the placeholder when the media is not played because the cookies have not been accepted.

<MediaPlayer
    url="https://www.youtube.com/embed/shT9-qX_y-w"
    placeholderSubtitle="or allow optional cookies to play it right here"
/>

placeholderImageUrl

A string that will be used as the background image of the placeholder when the media is not played because the cookies have not been accepted.

<MediaPlayer
    url="https://www.youtube.com/embed/shT9-qX_y-w"
    placeholderImageUrl="https://www.youtube.com/watch?v=hJ17RoZgwfk"
/>

The issue: Consumers that use coral-storyblok components typically use them out of the box and initialise them by just putting all of the components inside the storyblokInit function . This is fine for most components, but what if you need to provide props on a particular component that’ll persist across an entire space?

To provide CoralBlokMediaPlayer with persistent values for cookieKeyRequiredForConsent and onSubtitleClicked you can override the default component initialisation by doing the following:

import {
    CoralBlokMediaPlayer,
    coralBloks,
} from '@krakentech/coral-storyblok/rsc';
import { apiPlugin, storyblokInit } from '@storyblok/react/rsc';
import type { ComponentProps } from 'react';
 
const CoralBlokMediaPlayerWithDefaults = (
    props: ComponentProps<typeof CoralBlokMediaPlayer>
) => (
    <CoralBlokMediaPlayer
        blok={{
            ...props.blok,
            cookieKeyRequiredForConsent: 'marketing_and_social_media',
            onSubtitleClicked: () => {
                // remove cookies, local storage and reload the page
            },
        }}
    />
);
 
export const getStoryblokApi = storyblokInit({
    accessToken: process.env.storyblokAccessToken,
    use: [apiPlugin],
    apiOptions: {
        region: 'eu',
    },
    components: {
        ...coralBloks,
        coralBlokMediaPlayer: CoralBlokMediaPlayerWithDefaults,
    },
});

Full API

NameTypeDefault
attributesAttributes

This prop can be used to pass HTML attributes directly to the component. We currently allow passing data-* and aria-* attributes and the id. However, you can pass anything else with a type hack if necessary since this object is despread in to the component, without filtering its content.

Example usage:

AttributesProps: {
  'id': 'close-button',
  'aria-label': 'Close button',
  'data-testid': 'close-button'
};
urlstring

The URL of the media to display. Currently supports URLs from the following services: YouTube, Vimeo, SoundCloud, Spotify. Use the URL from the browser address bar when viewing the media on the respective platform’s website.

titlestring

The title of the media player.

aspectRatioAspectRatio

The aspect ratio of the media player.

16/9
cookieKeyRequiredForConsentstring

If your project sets granular cookies, you can provide the key required for consent to display the media player, for example, if you set the granular cookie ‘marketing_and_social_media’ to true, you can provide ‘marketing_and_social_media’ here to display the media player when that is accepted by the user.

placeholderTitlestring

Title shown in the placeholder when media cookies have not been accepted.

"Watch this on [PlatformName]"
placeholderSubtitlestring

Subtitle shown in the placeholder when media cookies have not been accepted.

"or allow optional cookies to see it right here"
placeholderImageUrlstring

Background image URL for the placeholder when media cookies have not been accepted.

onSubtitleClicked() => void

Callback function to be called when the subtitle is clicked.

Last updated on
LogoRadio