Skip to content

Embed (v1)

Embed component written in HTL that allows third-party widgets (e.g. chatbots, lead generation forms, social media posts, social pixels, videos etc.) to be added to a page.


  • The following input types are supported:
    • URL - an author is able to paste a URL of a widget to embed. URLs are checked against registered processors for a match. The following URL processors are provided:
      • oEmbed - generic oEmbed URL processor with out-of-the-box configurations for Facebook Post, Facebook Video, Flickr, Instagram, SoundCloud, Twitter and YouTube.
      • Pinterest - processes Pinterest URLs.
    • Embeddable - an author is able to select from pre-configured trusted embeddables. Embeddables can be parameterized and may include unsafe tags. A YouTube embeddable is included out-of-the-box.
    • HTML - an author is able to enter free-form HTML. HTML is restricted to safe tags only.
  • Each input type can be disabled by a template author.
  • For the embeddable type, the embeddables that are allowed to be selected in the edit dialog can be configured by a template author.

Component Policy Configuration Properties

The following configuration properties are used:

  1. ./urlDisabled - defines whether or not URL input is disabled in the edit dialog.
  2. ./embeddablesDisabled - defines whether or not embeddables are disabled in the edit dialog.
  3. ./htmlDisabled - defines whether or not free-form HTML input is disabled in the edit dialog.
  4. ./allowedEmbeddables - defines the embeddables that are allowed to be selected by an author when embeddables are not disabled.

Edit Dialog Properties

The following JCR properties are used:

  1. ./type - defines the input type to use. Types include URL, embeddable and HTML.
  2. ./url - defines the URL of the widget to embed.
  3. ./embeddableResourceType - defines the resource type of an embeddable.
  4. ./html - defines a HTML string to embed.

BEM Description

BLOCK cmp-embed

Extending the Embed Component

Please read the Security Recommendations before defining an extension.

Extension of the Embed component is possible by providing any of the following:

Custom URL Processor

By implementing the UrlProcessor interface you can create your own URL processor.

You will also need to create an HTL template file, with the same name as the processor field returned in the Result.


Custom oEmbed Configuration

By adding an OSGi configuration you can embed an URL from an oEmbed provider.


See also:

Custom embeddable fragment

By creating a hidden component with core/wcm/components/embed/v1/embed/embeddable super-type, you can define an embeddable that also supports edit configuration options.

To enable show/hide of the edit configuration options, the embeddable dialog snippet wrapper must have the following data attributes applied:


The JCR properties for the edit configuration options of an embeddable must be namespaced to prevent clashes. The following JCR properties are used for the provided YouTube embeddable:

  1. ./youtubeVideoId - defines the YouTube video ID.
  2. ./youtubeWidth - defines the YouTube video player width.
  3. ./youtubeHeight - defines the YouTube video player height.


Security Recommendations

  • Only implement URL processors and embeddables for trusted sources, as the payload returned by an endpoint may contain JavaScript.
  • Always fetch resources over HTTPS, without sslRelax set to true.
  • Do not use the unsafe HTL display context unless the payload is trusted.


If you were involved in the authoring of this component and are not credited above, please reach out to us on GitHub.

You can’t perform that action at this time.