πŸ“° React Social Media Embed

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

npm Version  View project on GitHub  Deploy Status

Buy me a coffee Sponsor

## Documentation Read the **[official documentation](https://justinmahar.github.io/react-social-media-embed/)**. ## 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 save you time, please consider buying me a coffee, which powers my development (and life). Your support is much appreciated! Sponsor via GitHub  Buy me a coffee  Buy me 3 coffees  Buy me 5 coffees ## Table of Contents - [Documentation](#documentation) - [Overview](#overview) - [Features include:](#features-include) - [Donate](#donate) - [Table of Contents](#table-of-contents) - [Installation](#installation) - [Usage](#usage) - [Facebook](#facebook) - [How do you get a Facebook post URL?](#how-do-you-get-a-facebook-post-url) - [IFrame Support](#iframe-support) - [Instagram](#instagram) - [How do you get an Instagram post URL?](#how-do-you-get-an-instagram-post-url) - [IFrame Support](#iframe-support-1) - [LinkedIn](#linkedin) - [How do you get a LinkedIn post URL?](#how-do-you-get-a-linkedin-post-url) - [Pinterest](#pinterest) - [How do you get a Pinterest pin URL?](#how-do-you-get-a-pinterest-pin-url) - [TikTok](#tiktok) - [How do you get a TikTok post URL?](#how-do-you-get-a-tiktok-post-url) - [IFrame Support](#iframe-support-2) - [X (Twitter)](#x-twitter) - [How do you get a X post URL?](#how-do-you-get-a-x-post-url) - [YouTube](#youtube) - [How do you get a YouTube video URL?](#how-do-you-get-a-youtube-video-url) - [Placeholder](#placeholder) - [How It Works](#how-it-works) - [Facebook](#facebook-1) - [Instagram](#instagram-1) - [LinkedIn](#linkedin-1) - [Pinterest](#pinterest-1) - [TikTok](#tiktok-1) - [X (Twitter)](#x-twitter-1) - [YouTube](#youtube-1) - [Thumbnail Refetching](#thumbnail-refetching) - [TypeScript](#typescript) - [Icon Attribution](#icon-attribution) - [Contributing](#contributing) - [⭐ Found It Helpful? Star It!](#-found-it-helpful-star-it) - [License](#license) ## Installation ``` npm i react-social-media-embed ``` ## Usage ### Facebook [πŸ‘οΈ View Demo](https://justinmahar.github.io/react-social-media-embed/?path=/docs/embeds-facebookembed--main-example) ```jsx import { FacebookEmbed } from 'react-social-media-embed'; ``` ```jsx
``` 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](https://justinmahar.github.io/react-social-media-embed/?path=/docs/embeds-facebookembed--main-example). #### 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](https://github.com/justinmahar/react-social-media-embed/issues/14#issuecomment-1297458134) for more info. #### IFrame Support For `iframe` support, you can provide `window` and `document` via the `frame` prop. ### Instagram [πŸ‘οΈ View Demo](https://justinmahar.github.io/react-social-media-embed/?path=/docs/embeds-instagramembed--main-example) ```jsx import { InstagramEmbed } from 'react-social-media-embed'; ``` ```jsx
``` This will display the Instagram embed centered with a width of `328`. To enable captions for the post, provide the `captioned` prop: ```jsx
``` For a live example and more options, read the [full documentation for InstagramEmbed](https://justinmahar.github.io/react-social-media-embed/?path=/docs/embeds-instagramembed--main-example). #### 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. ### LinkedIn [πŸ‘οΈ View Demo](https://justinmahar.github.io/react-social-media-embed/?path=/docs/embeds-linkedinembed--main-example) ```jsx import { LinkedInEmbed } from 'react-social-media-embed'; ``` ```jsx
``` 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](https://justinmahar.github.io/react-social-media-embed/?path=/docs/embeds-linkedinembed--main-example). #### 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`: ```html ``` 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. ### Pinterest [πŸ‘οΈ View Demo](https://justinmahar.github.io/react-social-media-embed/?path=/docs/embeds-pinterestembed--main-example) ```jsx import { PinterestEmbed } from 'react-social-media-embed'; ``` ```jsx
``` 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](https://justinmahar.github.io/react-social-media-embed/?path=/docs/embeds-pinterestembed--main-example). #### 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. ```html ``` ### TikTok [πŸ‘οΈ View Demo](https://justinmahar.github.io/react-social-media-embed/?path=/docs/embeds-tiktokembed--main-example) ```jsx import { TikTokEmbed } from 'react-social-media-embed'; ``` ```jsx
``` 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](https://justinmahar.github.io/react-social-media-embed/?path=/docs/embeds-tiktokembed--main-example). #### 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](https://justinmahar.github.io/react-social-media-embed/?path=/story/embeds-xembed--main-example) ```jsx import { XEmbed } from 'react-social-media-embed'; ``` ```jsx
``` This will display the X embed centered with a width of `325`. This component uses the [`react-twitter-embed`](https://www.npmjs.com/package/react-twitter-embed) package to embed content. You can specify props for the internal [`TwitterTweetEmbed`](https://github.com/saurabhnemade/react-twitter-embed#usage) component via the `twitterTweetEmbedProps` prop. For a live example and more options, read the [full documentation for XEmbed](https://justinmahar.github.io/react-social-media-embed/?path=/docs/embeds-xembed--main-example). #### 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](https://justinmahar.github.io/react-social-media-embed/?path=/docs/embeds-youtubeembed--main-example) ```jsx import { YouTubeEmbed } from 'react-social-media-embed'; ``` ```jsx
``` This will display the YouTube embed centered with a width of `325` and height of `220`. This component uses the [`react-youtube`](https://www.npmjs.com/package/react-youtube) package to embed content. You can specify props for the internal [`YouTube`](https://github.com/tjallingt/react-youtube#usage) component via the `youTubeProps` prop. For a live example and more options, read the [full documentation for YouTubeEmbed](https://justinmahar.github.io/react-social-media-embed/?path=/docs/embeds-youtubeembed--main-example). #### 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](https://justinmahar.github.io/react-social-media-embed/?path=/docs/placeholder-placeholderembed--main-example) ```jsx 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](https://justinmahar.github.io/react-social-media-embed/?path=/docs/placeholder-placeholderembed--main-example) 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](https://developers.facebook.com/docs/plugins/embedded-posts/) to embed content. This loads a script which initializes the Facebook embedder to `window.FB.XFBML`. A Facebook post uses the following form: ```html
``` We then use the [`FB.XFBML.parse()`](https://developers.facebook.com/docs/reference/javascript/FB.XFBML.parse/) function to manually initialize the embed HTML. ### Instagram We use the [Instagram embed.js JavaScript library](https://developers.facebook.com/docs/plugins/embedded-posts/) 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: ```html
Placeholder
``` We then use the [`instgrm.Embeds.process()`](https://developers.facebook.com/docs/instagram/oembed/) function to manually initialize the embed HTML. ### LinkedIn 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. ### Pinterest 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](https://developers.tiktok.com/doc/embed-videos) to embed content. This loads a [script](https://www.tiktok.com/embed.js) which initializes the TikTok embedder to `window.tiktokEmbed`. A TikTok post uses the following form: ```html
Placeholder
``` 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!](https://github.com/justinmahar/react-social-media-embed/issues/new)** 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: ```html ``` Again, if there's a way to manually initialize the embed HTML through the already-loaded script, please [open an issue](https://github.com/justinmahar/react-social-media-embed/issues/new) so this can be improved. For now, this gets the job done! ### X (Twitter) We use the [`react-twitter-embed`](https://www.npmjs.com/package/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`](https://github.com/saurabhnemade/react-twitter-embed#usage) component via the `twitterTweetEmbedProps` prop. ### YouTube We use the [`react-youtube`](https://www.npmjs.com/package/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`](https://github.com/tjallingt/react-youtube#usage) component via the `youTubeProps` prop. #### Thumbnail Refetching If you have problems with pixelated thumbnails, try this solution to trigger thumbnail refetching: ```jsx const YOUTUBE_DEFAULT_HEIGHT = 390; const [embedHeight, setEmbedHeight] = React.useState(YOUTUBE_DEFAULT_HEIGHT); (await r.target.getIframe()).addEventListener('load', () => setEmbedHeight((height) => height + 1)), }} /> ``` ## TypeScript Type definitions have been included for [TypeScript](https://www.typescriptlang.org/) support. ## Icon Attribution Favicon by [Twemoji](https://github.com/twitter/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!](https://github.com/justinmahar/react-social-media-embed/stargazers) If you found this project helpful, let the community know by giving it a [star](https://github.com/justinmahar/react-social-media-embed/stargazers): [πŸ‘‰β­](https://github.com/justinmahar/react-social-media-embed/stargazers) Want to support the project? Feel free to grab me a coffee, which is my main source of fuel for development: Buy me a coffee  Buy me 3 coffees  Buy me 5 coffees ## License See [LICENSE.md](https://justinmahar.github.io/react-social-media-embed/?path=/docs/license--docs).