React Tiny Oembed

React component for embedding content from sites going oEembed way and only[1] oembed way. Just give it a URL and it will do the rest, no more paying for widgets!

The motivation behind this component is the admiration of oembed, an opensource standard with a unified way of embedding content from all supported sites, instead of having different methods for every site.

[1] However sites not supporting oembed for now can also be embedded using oembed wrapper proxies and interceptors, see Plugins below

Installation

npm install react-tiny-oembed

requires React 16.8 or higher

Basic usage

import Embed from 'react-tiny-oembed'

function App() {
    ...

        <Embed
            url="https://youtu.be/nlD9JYP8u5E"
            proxy="https://cors-anywhere.herokuapp.com/"
        />
}

A note on the proxy: most of the sites do not have cors enabled, so cors proxy is necessary in most cases. The above-used proxy is just for demonstration and is slow and highly rate-limited, so provide your own proxy. You can host Cors anywhere on your own node server and use that.

By default only YouTube, Reddit, Flickr, Vimeo, SoundCloud, Twitter, GIPHY are enabled, to add more or reduce even default ones, see providers prop below.

Props

You can pass multiple props to the Embed component, typings can be imported as named exports.

• options: EmbedRequestOptions

  An object containing oembed options, these fields are used as query params to oembed provider, these include general options like maxwidth and maxheight and also some site-specific options. Below are some of the default ones used.

  value	type	default	description
  maxwidth	number	700	maximum width of the iframe or image rendered by the provider. Note that this is separate from the outer container
  maxheight	number	400	similar to the maxwidth
  align	string	'center'	for twitter

• style: CSSProperties

  Styles applied to outer container, container also has __embed class so you can use that too, by default it has 100% width and 700px max width.

• FallbackElement and LoadingFallbackElement: ReactElement

  By default the given URL is shown as an anchor tag (external) for states like loading, error, etc. However, you can pass your own elements like

  <Embed
      options={{ theme: 'dark' }}
      url="https://twitter.com/iamdevloper/status/1324864523363356673"
      proxy="https://cors-anywhere.herokuapp.com/"
      LoadingFallbackElement="Yeah loading..., use your own proxy"
  />

• ImgComponent: ComponentType<{ responce?: PhotoEmbedResponce }>

  While most sites will render some good-looking widgets, some sites like Giphy will just render a plain image. Images are displayed plain, without any styling, you might want to have your own custom component for images. That component will receive the responce prop as oembed responce object. For example, you can access src via responce.url.

      function CustomImg({ responce }) {
          return <div className="img-widget">
              <h1>Image from {responce.provider_name}</h1>
              <img src={responce.url} alt={responce.author_name} />
          </div>
      }
  
      ...
          <Embed
              ...
              ImgComponent={CustomImg}
          />

  similar is for LinkComponent but I did not see any site returning just link!

• providers ⭐

  Default providers are just a handful, you have hundreds to choose from. This prop can be used to enable (or reduce) support for individual sites. It expects an array of Provider objects which define matching patterns for links, embedding URLs or interceptors to add to.

  Say you want to extend support for more sites, go to https://oembed.com/providers.json, choose a provider object and pass that to this prop. Say we pick the first one, TwoThreeHQ, we will use it like this.

      import Embed, { defaultProviders } from 'react-oembed'
  
      const TwoThreeHQ = {
          "provider_name": "23HQ",
          "provider_url": "http:\/\/www.23hq.com",
          "endpoints": [
              {
                  "schemes": [
                      "http:\/\/www.23hq.com\/*\/photo\/*"
                  ],
                  "url": "http:\/\/www.23hq.com\/23\/oembed"
              }
          ]
      }
  
      ...
  
          <Embed
              url= ...
  
              providers={[...defaultProviders, TwoThreeHQ]}
          />

  Note: Passing the providers list overrides the default one, so you need to pass defaultProviders to have them too.

  Note: Providers like Instagram and Facebook require developer keys too, so pass them in the options prop above (testing TBD).

  If you want to filter out even the default ones, you can

  const providers = defaultProviders.filter(
      p => p.provider_name === 'Vimeo' || p.provider_name === 'SoundCloud'
  )

  For sites not supporting oembed but see Plugins section below.

Plugins

• github-gist - Github gist sample plugin for react-tiny-oembed without a proxy server.
• ...others

For authoring plugins see PLUGINS

Contributing

Contributions welcome!