Skip to content
This repository has been archived by the owner. It is now read-only.
Media embed plugin for Kirby 2 CMS
Branch: master
Clone or download
Latest commit 23d5234 Jan 28, 2019

Embed for Kirby 2 CMS

Release Issues Kirby Version

Embed extends Kirby with some extensive media embed functionalities. It enables Kirby to display embeds from various media sites (e.g. YouTube, Vimeo, Soundcloud, Instagram etc.) by only providing the URL to the medium. It is powered by the oscarotero/Embed library.

With the release of Kirby 3, this plugin has been archived and will not be maintained.

Table of Contents

  1. Requirements
  2. Installation & Update
  3. Usage
  4. Options
  5. Panel field
  6. Advanced
  7. Styles, Scripts & Translations
  8. Examples
  9. Help & Improve
  10. Version History


Kirby CMS 2.3.0+ and PHP 5.5+.

Installation & Update

  1. Download Embed and add the files to site/plugins/embed/
  2. Add the necessary styles by including the following in the header:
<?= css('assets/plugins/embed/css/embed.css') ?>

With video lazyload option (activated by default, include unless deactived)

  1. Add the necessary script by including the following right before the </body> tag:
<?= js('assets/plugins/embed/js/embed.js') ?>

With the Kirby CLI

kirby plugin:install distantnative/embed

And add CSS and JS as outlined above.


As field method in templates:
Use the method on fields that contain a url that points to a supported medium (e.g. YouTube, Vimeo, Twitter, Instagram, Spotify etc.):

<?= $page->tweet()->embed(); ?>

You can use any text field containing a valid URL, but you might want to use the designated Embed panel field.

As Kirbytext tag:

You'll be given love. You'll be taken care of. You'll be given love. You have to trust it. Maybe not from the sources. You have poured yours. Maybe not from the directions. You are staring at.


Twist your head around. It's all around you. All is full of love. All around you. All is full of love. You just ain't receiving. All is full of love. Your phone is off the hook. All is full of love. Your doors are all shut. All is full of love.

As global PHP helper function:

<?= embed('') ?>


Per embed

You can set the following options on each embed to apply:

// with the field method
<?= $page->featured_video()->embed([
  'lazyvideo' => true
]) ?>

// with the Kirbytext tag
(embed: lazyvideo: true)
Option Values Description
class (string) Class to be added to the embed wrapper
thumb (string) Custom thumbnail (URL)
autoplay true/false Starts the embedded video automatically
lazyvideo true/false Lazyload the embedded video
jsapi true/false Activates the JS API of certain providers


You can set the following options in your site/config/config.php to generally apply to all embeds:

c::set('', false);

c::set('', true);
c::set('', 'assets/plugins/embed/images/play.png');

c::set('plugin.embed.caching', true);
c::set('plugin.embed.caching.duration', 24); // in hours

c::set('plugin.embed.w3c.enforce', false);

c::set('plugin.embed.providers.jsapi', false);
c::set('', null);
c::set('plugin.embed.providers.soundcloud.key', null):

URL parameters

Embed supports various URL parameters of provider that usually get lost during the embed call. To see which parameters are supported, please use the panel field and switch on the cheatsheet option.

Panel field

Embed also includes its own panel field which provides a preview of the embedded medium right inside the panel:

// in your blueprint
    label: Featured video
    type:  embed

With its additional options you can also disable the preview section, the information section as well as the cheatsheet or set a max-height for the preview:

    label:      Featured video
    type:       embed
    preview:    false
    info:       false
    cheatsheet: false
    height:     250px

Panel field preview
Panel field preview


Embed does not only provide you an easy way to output the embed code, but also gives you access to a whole array of additional information provided by the oscarotero/Embed library.

// instead of echoing the field method, use it for further details:

$info = $page->video()->embed();
echo $info->description();
echo $info->authorName();

You can find a full overview of what information can be accessed in the documentation of the oscarotero/Embed library or also just test your media URL and see what information is available.

Styles, Scripts & Translations

Embed comes with very minimal styles, mainly for embedded videos and only a small script necessary when lazyloading videos (activated by default):

// Include styles
<?= css('assets/plugins/embed/css/embed.css') ?>

// Include script
<?= js('assets/plugins/embed/js/embed.js') ?>

If you want to further customize and work with the embedded medium. The following CSS classes are applied to the main wrapper:

.embed--{TYPE}      // e.g. video, rich
.embed--{PROVIDER}  // e.g. YouTube, Vimeo

.embed__thumb > img

You can also translate the strings used by Embed. Translations for English and German are already included. To find out what keys to use, check out the English translation file.


Blog: Featured Embed

// site/blueprints/article.yml
    Cover photo
    type: image
    label: Featured embed (instead of cover photo)
    type:  embed
// site/snippets/article.php
  <aside class="entry-meta">...</aside>
  <div class="entry-main">
    <?php if($page->featured()->isNotEmpty()): ?>
      <figure class="entry-cover">
        <?= $page->featured()->embed() ?>
    <?php elseif($page->cover()->isNotEmpty()) : ?>
      <figure class="entry-cover">
        <?= $page->cover() ?>
    <?php endif; ?>
    <div class="entry-content"><?= $page->text()->kt() ?></div>


Video from Vimeo:

Tweet from Twitter:

Player from Spotify:

Help & Improve

If you have any suggestions for further configuration options, please let me know.

Version history

You can find a more or less complete version history in the changelog.


MIT License


Nico Hoffmann -

You can’t perform that action at this time.