Skip to content


A oembed field supports the user in embedding media hosted by any oembed—compatible hosting site, or any site for which you have provided an oembetter filter via the @apostrophecms/oembed module.

The field will immediately preview the media embed after entering a valid URL.

The database value of the field will have url, title and thumbnail properties. title and thumbnail are snapshots from the oembed response at the time the field was saved. thumbnail is the URL of a thumbnail image as provided by the oembed response. Developers should retrieve the full embed code in client-side code to get the latest version available.

Module field definition

// Configuring the `video` field in a module's `fields.add` subsection:
video: {
  type: 'oembed',
  label: 'Featured video'



labelStringn/aSets the visible label for the field in the UI
typeStringn/aSpecifies the field type (float for this type)


helpStringn/aHelp text for the content editor
htmlHelpStringn/aHelp text with support for HTML markup
ifObject{}Conditions to meet before the field is active. See the guide for details.
requiredIfObject{}Conditions to meet before the field is required. See the guide for details.
hiddenBooleanfalseIf true, the field is hidden
requiredBooleanfalseIf true, the field is mandatory
readOnlyBooleanfalseIf true, prevents the user from editing the field value

Use in templates

Simplest usage could involve simply printing the thumbnail image (if available) and linking to the media:

{% if and %}
  {% set video = %}
  <a href="{{ video.url }}">
    <img src="{{ video.thumbnail }}" alt="{{ video.title }}">
{% endif %}

More likely, you will want to add the full embed code from the media source. This should be done in client-side JavaScript. Apostrophe provides an API route to get that.

Submit a GET request to /api/v1/@apostrophecms/oembed/query with the media URL as the url query parameter. A successful response will be an object with several properties to help place and style the embed, including an html property with the actual HTML markup to embed.

The @apostrophecms/video-widget widget provides a full-featured implementation. It includes a widget player that uses that API route to retrieve the full embed code and then replaces a placeholder HTML element with that code. See that widget for a suggested implementation.