ReqEmbed (ReqEmbed v0.2.3)

View Source

Req plugin for oEmbed.

Features

  • Auto-Discovery: Finds oEmbed endpoints via HTML link tags (oEmbed discovery)
  • 300+ Providers: YouTube, Twitter, Instagram, and more
  • Content Types: Video, Photo, Rich media, and Link embeds
  • Phoenix Ready: HEEx component and HTML helpers
  • Customizable: CSS classes, responsive design, and embed options

Installation

Add :req_embed dependency:

def deps do
  [
    {:req_embed, "~> 0.2"}
  ]
end

Or use Igniter:

mix igniter.install req_embed

Usage

Req plugin

req = Req.new() |> ReqEmbed.attach()

Req.get!(req, url: "https://www.youtube.com/watch?v=XfELJU1mRMg").body
#=>
# %ReqEmbed.Video{
#   type: "video",
#   version: "1.0",
#   title: "Rick Astley - Never Gonna Give You Up (Official Music Video)",
#   author_name: "Supirorguy508",
#   author_url: "https://www.youtube.com/@supirorguy5086",
#   provider_name: "YouTube",
#   provider_url: "https://www.youtube.com/",
#   cache_age: nil,
#   thumbnail_url: "https://i.ytimg.com/vi/XfELJU1mRMg/hqdefault.jpg",
#   thumbnail_width: 480,
#   thumbnail_height: 360,
#   html: "<iframe width=\"200\" height=\"113\" src=\"https://www.youtube.com/embed/XfELJU1mRMg?feature=oembed\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share\" referrerpolicy=\"strict-origin-when-cross-origin\" allowfullscreen title=\"Rick Astley - Never Gonna Give You Up (Official Music Video)\"></iframe>",
#   width: 200,
#   height: 113
# }

When successful, the response body will contain either one of the following structs representing the oEmbed type:

Phoenix Component

Use ReqEmbed.embed/1 to display oEmbed content in HEEx templates:

<ReqEmbed.embed url="https://www.youtube.com/watch?v=XfELJU1mRMg" class="aspect-video" />

Renders:

<iframe allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="allowfullscreen" class="aspect-video" frameborder="0" referrerpolicy="strict-origin-when-cross-origin" src="https://www.youtube.com/embed/XfELJU1mRMg?feature=oembed" title="Rick Astley - Never Gonna Give You Up (Official Music Video)"></iframe>

Note that :phoenix_live_view is required to use the component, it's not a direct dependency.

Raw HTML

Or alternatively use ReqEmbed.html/2 to get the oEmbed content as HTML:

ReqEmbed.html("https://www.youtube.com/watch?v=XfELJU1mRMg")
# <iframe width="200" height="113" src="https://www.youtube.com/embed/XfELJU1mRMg?feature=oembed" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen title="Rick Astley - Never Gonna Give You Up (Official Music Video)"></iframe>

Wrap it in a {:safe, html} tuple or call Phoenix.HTML.raw/1 to render it in Phoenix templates.

Summary

Functions

attach(request, options \\ [])

Attach the oEmbed plugin into Req.

embed(assigns)

Phoenix Component to render oEmbed content.

html(url, opts \\ [])

Render the oEmbed content as HTML.

Functions

attach(request, options \\ [])

@spec attach(
  Req.Request.t(),
  keyword()
) :: Req.Request.t()

Attach the oEmbed plugin into Req.

Options

  • :query (map/0) - Defaults to %{}. The query parameters to be sent to the oEmbed endpoint, like :maxwidth, :maxheight, and others supported by the provider. The parameters :url and :format are managed by the plugin, you can't override them. See section 2.2 Consumer Request for more info.

  • :discover (boolean/0) - Defaults to true. When enabled, it will first attempt to auto-discover the oEmbed endpoint by looking for the link tag in the HTML response. If no link tag is found, it will fallback to searching for a known provider endpoint. When disabled, it will skip the HTML parsing step and only use the known provider endpoints.

Examples

iex> req = Req.new() |> ReqEmbed.attach()
iex> Req.get!(req, url: "https://x.com/ThinkingElixir/status/1848702455313318251").body
iex> %ReqEmbed.Rich{
       type: "rich",
       version: "1.0",
       author_name: "ThinkingElixir",
       author_url: "https://twitter.com/ThinkingElixir",
       html: "<blockquote class="twitter-tweet"><p lang="en" dir="ltr">News includes upcoming Elixir v1.18 ...
       ...
     }

embed(assigns)

Phoenix Component to render oEmbed content.

Requires phoenix_live_view to be installed, otherwise you can use html/2 directly.

This component is essentially a wrapper for html/2.

See ReqEmbed.Component.embed/1 for attributes doc.

Example

def render(assigns) do
  ~H"""
  <%= ReqEmbed.embed(url: "https://www.youtube.com/watch?v=XfELJU1mRMg") %>
  """
end

html(url, opts \\ [])

Render the oEmbed content as HTML.

Options

  • :class (String.t/0) - Defaults to nil. CSS class to be added into the <iframe> tag, if used it removes both width and height attributes.
  • :include_caption (boolean/0) - Defaults to true. When enabled, it will include the photo title in <figcaption>.

Examples

iex> ReqEmbed.html("https://www.youtube.com/watch?v=XfELJU1mRMg")
<iframe width="200" height="113" src="https://www.youtube.com/embed/XfELJU1mRMg?feature=oembed" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen title="Rick Astley - Never Gonna Give You Up (Official Music Video)"></iframe>

Replace the width and height attributes with a CSS class:

iex> ReqEmbed.html("https://www.youtube.com/watch?v=XfELJU1mRMg", class: "aspect-video")
<iframe class="aspect-video" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="allowfullscreen" frameborder="0" referrerpolicy="strict-origin-when-cross-origin" src="https://www.youtube.com/embed/XfELJU1mRMg?feature=oembed" title="Rick Astley - Never Gonna Give You Up (Official Music Video)"></iframe>

Wrap it in a {:safe, html} tuple or call Phoenix.HTML.raw/1 to render it in Phoenix templates.