justinmahar/react-social-media-embed

📰 React Social Media Embed

Easily embed social media posts from Facebook, Instagram, LinkedIn, Pinterest, TikTok, X (Twitter), and YouTube in React.

Documentation

Read the official documentation.

Overview

Easily embed content from several popular social media platforms in React.

All embeds only require a URL to the post. No API token is needed.

Currently supporting: Facebook, Instagram, LinkedIn, Pinterest, TikTok, X (Twitter), and YouTube.

Features include:

🚀 Quick and easy
- Embed content quickly and easily for the most popular social media platforms. Just provide a URL!
💁 Live demos
- Give the embeds a try and play with their props using live examples.
⚙️ Customizable
- Each embed supports all div props and provides additional options, such as a placeholder.
💪 Resilient
- If embedding fails, it automatically retries using a configurable retry delay.

Donate

If this project helped you, please consider buying me a coffee or sponsoring me. Your support is much appreciated!

Documentation
Overview
- Features include:
Donate
Table of Contents
Installation
Usage
How It Works
- Facebook
- Instagram
- LinkedIn
- Pinterest
- TikTok
- X (Twitter)
- YouTube
- Thumbnail Refetching
TypeScript
Icon Attribution
Contributing
⭐ Found It Helpful? Star It!
License

Installation

npm i react-social-media-embed

Usage

Facebook

👁️ View Demo

import { FacebookEmbed } from 'react-social-media-embed';

<div style={{ display: 'flex', justifyContent: 'center' }}>
  <FacebookEmbed url="https://www.facebook.com/andrewismusic/posts/451971596293956" width={550} />
</div>

This will display the Facebook embed centered with a width of 550.

For a live example and more options, read the full documentation for FacebookEmbed.

How do you get a Facebook post URL?

For the post you'd like to embed, select ⋯ › Embed › Advanced settings › Get Code, then use the cite link in the generated blockquote.

See these instructions which include screenshots for more info.

IFrame Support

For iframe support, you can provide window and document via the frame prop.

Instagram

👁️ View Demo

import { InstagramEmbed } from 'react-social-media-embed';

<div style={{ display: 'flex', justifyContent: 'center' }}>
  <InstagramEmbed url="https://www.instagram.com/p/CUbHfhpswxt/" width={328} />
</div>

This will display the Instagram embed centered with a width of 328.

To enable captions for the post, provide the captioned prop:

<div style={{ display: 'flex', justifyContent: 'center' }}>
  <InstagramEmbed url="https://www.instagram.com/p/CUbHfhpswxt/" width={328} captioned />
</div>

For a live example and more options, read the full documentation for InstagramEmbed.

How do you get an Instagram post URL?

A few options:

Open a post and select … > Copy Link
Open a post in a browser window and copy the URL from the address bar. The URL should be in the format: https://www.instagram.com/p/abc123xyzAB/
Open a post and select … > Embed > Copy embed code. Paste the embed code in a text editor, then locate the data-instgrm-permalink attribute and use that link.

IFrame Support

For iframe support, you can provide window and document via the frame prop.

👁️ View Demo

import { LinkedInEmbed } from 'react-social-media-embed';

<div style={{ display: 'flex', justifyContent: 'center' }}>
  <LinkedInEmbed 
    url="https://www.linkedin.com/embed/feed/update/urn:li:share:6898694772484112384"
    postUrl="https://www.linkedin.com/posts/peterdiamandis_5-discoveries-the-james-webb-telescope-will-activity-6898694773406875648-z-D7"
    width={325}
    height={570} 
  />
</div>

This will display the LinkedIn embed centered with a width of 325 and height of 570.

For a live example and more options, read the full documentation for LinkedInEmbed.

How do you get a LinkedIn post URL?

The url must be be retrieved from the "Embed this post" option for the desired post. Use the src attribute of the iframe:

<iframe src="https://www.linkedin.com/embed/feed/update/urn:li:share:6898694772484112384" height="570" width="325" frameborder="0" allowfullscreen="" title="Embedded post"></iframe>

It is recommended that you specify the width and height of the post. These have been pre-calculated in the iframe embed code as well.

You can also specify a postUrl which will be used in the placeholder to link to the regular, non-embed version of the post.

👁️ View Demo

import { PinterestEmbed } from 'react-social-media-embed';

<div style={{ display: 'flex', justifyContent: 'center' }}>
  <PinterestEmbed 
    url="https://www.pinterest.co.uk/pin/875105771321194304/"
    width={345}
    height={467}
  />
</div>

This will display the Pinterest embed centered with a width of 345. You can specify a height if you'd like to adjust how much of the pin is vertically shown. See below for determining the correct width and height to use.

For a live example and more options, read the full documentation for PinterestEmbed.

How do you get a Pinterest pin URL?

Visit a Pinterest post in your browser. Copy the URL from the address bar.

The URL must contain the pin ID, in the format pin/1234567890123456789. Short links are not supported.

It is recommended that you specify the width and height of the post. These have been pre-calculated in the iframe embed code provided by Pinterest for the post.

Select the ellipsis ... by the post and select "Get Pin embed code". Then use the height and width shown for the post you'd like to embed.

<iframe src="https://assets.pinterest.com/ext/embed.html?id=875105771321194304" height="467" width="345" frameborder="0" scrolling="no" ></iframe>

TikTok

👁️ View Demo

import { TikTokEmbed } from 'react-social-media-embed';

<div style={{ display: 'flex', justifyContent: 'center' }}>
  <TikTokEmbed url="https://www.tiktok.com/@epicgardening/video/7055411162212633903" width={325} />
</div>

This will display the TikTok embed centered with a width of 325.

For a live example and more options, read the full documentation for TikTokEmbed.

How do you get a TikTok post URL?

Open a post in your browser. The post URL will be shown. Click the Copy Link button.

The URL must contain the video ID, in the format https://www.tiktok.com/@username/video/1234567890123456789. Short links are not supported.

IFrame Support

For iframe support, you can provide window and document via the frame prop.

X (Twitter)

👁️ View Demo

import { XEmbed } from 'react-social-media-embed';

<div style={{ display: 'flex', justifyContent: 'center' }}>
  <XEmbed url="https://twitter.com/PixelAndBracket/status/1356633038717923333" width={325} />
</div>

This will display the X embed centered with a width of 325.

This component uses the react-twitter-embed package to embed content. You can specify props for the internal TwitterTweetEmbed component via the twitterTweetEmbedProps prop.

For a live example and more options, read the full documentation for XEmbed.

How do you get a X post URL?

Open an X post in a browser window. Copy the link to the post from the address bar.

The URL must contain the post ID, in the format https://twitter.com/username/status/1234567890123456789. Short links are not supported.

Alternate option: Select … > Embed Post, and use the a href attribute value from the provided embed code.

YouTube

👁️ View Demo

import { YouTubeEmbed } from 'react-social-media-embed';

<div style={{ display: 'flex', justifyContent: 'center' }}>
  <YouTubeEmbed url="https://www.youtube.com/watch?v=HpVOs5imUN0" width={325} height={220} />
</div>

This will display the YouTube embed centered with a width of 325 and height of 220.

This component uses the react-youtube package to embed content. You can specify props for the internal YouTube component via the youTubeProps prop.

For a live example and more options, read the full documentation for YouTubeEmbed.

How do you get a YouTube video URL?

Open the video in a browser window. Copy the URL from the address bar. You can also click Share > Copy.

The URL must be in the format https://www.youtube.com/watch?v=VIDEO_ID or https://youtu.be/VIDEO_ID where VIDEO_ID is the video ID.

YouTube Shorts are also supported. For shorts, the URL must be in the format https://youtube.com/shorts/VIDEO_ID.

Placeholder

👁️ View Demo

import { PlaceholderEmbed } from 'react-social-media-embed';

A placeholder is shown while loading. If you do not specify a placeholder via the embedPlaceholder prop, a default PlaceholderEmbed placeholder component will be used. You can disable the placeholder with the placeholderDisabled prop.

The default placeholder will size itself according to the width and/or height you specify for the embed. If none are specified, it will fall back to a default size appropriate for the given social media platform. You can pass custom props (such as style) to the default placeholder via placeholderProps to override any default behavior.

If you'd like, you can specify the placeholderImageUrl prop to any of the embeds to show a placeholder with the provided image.

By default, the placeholder spinner is a BorderSpinner with a width/height of 10 and 25% transparent black border of 3px. You can specify the placeholderSpinner prop to provide your own custom spinner, and the placeholderSpinnerDisabled prop to remove the placeholder spinner altogether.

See the PlaceholderEmbed docs for examples and more.

How It Works

Each embed has a slightly different implementation. I've tried my best to standardize the embed experience for each from a developer standpoint so you don't have to think about how it performs the embed.

If you're curious how the embeds happen, read on!

Facebook

We use the Facebook JavaScript SDK to embed content.

This loads a script which initializes the Facebook embedder to window.FB.XFBML.

A Facebook post uses the following form:

<div class="fb-post" data-href="https://github.com/justinmahar/react-social-media-embed/blob/master/{your-post-url}"></div>

We then use the FB.XFBML.parse() function to manually initialize the embed HTML.

Instagram

We use the Instagram embed.js JavaScript library to embed content. In the documentation, you can refer to the section titled "Embed JS" for details.

This loads a script which initializes the Instagram embedder to window.instgrm.Embeds.

An Instagram post uses the following form:

<blockquote class="instagram-media"
            data-instgrm-permalink="{your-post-url}"
            data-instgrm-version="14">
  <div>Placeholder</div>
</blockquote>

We then use the instgrm.Embeds.process() function to manually initialize the embed HTML.

LinkedIn does not have an embed JS library, unfortunately. So we use a simple iframe with the embed URL from LinkedIn's embed option, which is accessed via the menu next to any given post that has embedding allowed. If a post does not have embedding allowed, this option will not appear.

LinkedIn provides you with an iframe with an src attribute and the calculated width and height. Use these attributes for your embed.

We use a simple iframe with the URL of the Pinterest pin you'd like to embed.

Pinterest provides you with embed code containing an iframe with the calculated width and height. The embed code is accessed via the menu next to any given pin that has embedding allowed. Use these width and height attributes for your embed.

TikTok

We use the TikTok embed.js JavaScript library to embed content.

This loads a script which initializes the TikTok embedder to window.tiktokEmbed.

A TikTok post uses the following form:

<blockquote class="tiktok-embed" cite="{your-post-url}" data-video-id="{video-id}">
  <div>Placeholder</div>
</blockquote>

Unfortunately, unlike Facebook and Instagram, there is no documented or obvious way to manually initialize the embed HTML. If you know how to do this, please open a GitHub issue with the info!

So, in order to initialize the embed HTML, we must load the embed script from TikTok every time we render the TikTok embed. To do this, we use time-based query param cache busting and replace the embed.js script element in the head node. This forces the browser to load the script anew each time, which then performs the embed.

For example, here's the script element with t as the current time:

<script src="https://www.tiktok.com/embed.js?t=1645275849920" id="tiktok-embed-script"></script>

Again, if there's a way to manually initialize the embed HTML through the already-loaded script, please open an issue so this can be improved. For now, this gets the job done!

X (Twitter)

We use the react-twitter-embed package to embed X posts. This completely amazing package does all the heavy lifting. Please consider supporting the project.

You can specify props for the internal TwitterTweetEmbed component via the twitterTweetEmbedProps prop.

YouTube

We use the react-youtube package to embed YouTube videos. This incredibly awesome package does all the heavy lifting. Please consider supporting the project.

You can specify props for the internal YouTube component via the youTubeProps prop.

Thumbnail Refetching

If you have problems with pixelated thumbnails, try this solution to trigger thumbnail refetching:

const YOUTUBE_DEFAULT_HEIGHT = 390;
const [embedHeight, setEmbedHeight] = React.useState(YOUTUBE_DEFAULT_HEIGHT);

<YouTubeEmbed
  height={embedHeight}
  youTubeProps={{
    onReady: async (r) =>
      (await r.target.getIframe()).addEventListener('load', () => setEmbedHeight((height) => height + 1)),
  }}
/>

TypeScript

Type definitions have been included for TypeScript support.

Icon Attribution

Favicon by Twemoji.

Contributing

Open source software is awesome and so are you. 😎

Feel free to submit a pull request for bugs or additions, and make sure to update tests as appropriate. If you find a mistake in the docs, send a PR! Even the smallest changes help.

For major changes, open an issue first to discuss what you'd like to change.

⭐ Found It Helpful? Star It!

If you found this project helpful, let the community know by giving it a star: 👉⭐

License

See LICENSE.md.