API Reference

Tweet

import { Tweet } from 'react-x-embed'

<Tweet id="2040511285998313827">

Fetches and renders the tweet. It accepts the following props:

• id - string: the tweet ID. For example in https://x.com/chibicode/status/2040511285998313827 the tweet ID is 2040511285998313827. This is the only required prop.
• apiUrl - string: the API URL to fetch the tweet from when using the tweet client-side with SWR. Defaults to https://react-tweet.vercel.app/api/tweet/:id.
• fallback - ReactNode: The fallback component to render while the tweet is loading. Defaults to TweetSkeleton.
• onError - (error?: any) => any: The returned error will be sent to the TweetNotFound component.
• components - TwitterComponents: Components to replace the default tweet components. See the custom tweet components section for more details.
• fetchOptions - RequestInit: options to pass to fetch.

If the environment where Tweet is used does not support React Server Components then it will work with SWR  instead and the tweet will be fetched from https://react-tweet.vercel.app/api/tweet/:id, which is CORS friendly.

We highly recommend adding your own API route to fetch the tweet in production (as we cannot guarantee our IP will not get limited). You can do it by using the apiUrl prop:

<Tweet apiUrl={id && `/api/tweet/${id}`} />

Note: apiUrl does nothing if the Tweet is rendered in a server component because it can fetch directly from Twitter’s CDN.

Here’s a good example of how to setup your own API route:

import type { VercelRequest, VercelResponse } from '@vercel/node'
import { getTweet } from 'react-x-embed/api'
 
const handler = async (req: VercelRequest, res: VercelResponse) => {
  const tweetId = req.query.tweet
 
  if (req.method !== 'GET' || typeof tweetId !== 'string') {
    res.status(400).json({ error: 'Bad Request.' })
    return
  }
 
  try {
    const tweet = await getTweet(tweetId)
    res.status(tweet ? 200 : 404).json({ data: tweet ?? null })
  } catch (error) {
    console.error(error)
    res.status(400).json({ error: error.message ?? 'Bad request.' })
  }
}
 
export default handler

Something similar can be done with Next.js API Routes or Route Handlers.

EmbeddedTweet

import { EmbeddedTweet } from 'react-x-embed'

Renders a tweet. It accepts the following props:

• tweet - Tweet: the tweet data, as returned by getTweet. Required.
• components - TwitterComponents: Components to replace the default tweet components. See the custom tweet components section for more details.

TweetCard

import { TweetCard } from 'react-x-embed'

Renders the preview of a link shared in a tweet — image, domain, title and description. It accepts the following props:

• tweet - EnrichedTweet: the tweet data, as returned by enrichTweet. Required.

Renders nothing unless the tweet carries a card with a title. Cards without one (player, unified_card, ad formats) are skipped, since the link already appears inline in the tweet text.

EmbeddedTweet renders this already, and only when the tweet has no media of its own — a tweet’s own photos or video take precedence over a link preview, matching X. You only need it directly when building custom components.

TweetMediaVideo

import { TweetMediaVideo } from 'react-x-embed'

Renders a video, with the poster frame and play button. It accepts the following props:

• tweet - EnrichedTweet | EnrichedQuotedTweet: the enriched tweet. Required.
• media - MediaAnimatedGif | MediaVideo: the media item to render. Required.
• quality - 'low' | 'medium' | 'high': which mp4 rendition to play. Defaults to medium, which skips the highest bitrate — usually far larger than an inline embed needs.

X’s HLS rendition is rendered as an additional <source> listed before the mp4, because Safari supports HLS natively and plays it more reliably than X’s mp4 endpoints, which don’t consistently honour byte-range requests.

TweetSkeleton

import { TweetSkeleton } from 'react-x-embed'

A tweet skeleton useful for loading states.

TweetNotFound

import { TweetNotFound } from 'react-x-embed'

A tweet not found component. It accepts the following props:

• error - any: the error that was thrown when fetching the tweet. Not required.

Custom tweet components

Default components used by Tweet and EmbeddedTweet can be replaced by passing a components prop. It extends the TwitterComponents type exported from react-x-embed:

type TwitterComponents = {
  TweetNotFound?: (props: Props) => JSX.Element
  AvatarImg?: (props: AvatarImgProps) => JSX.Element
  MediaImg?: (props: MediaImgProps) => JSX.Element
}

MediaImg receives srcSet and sizes alongside src, so a replacement should forward them — dropping them costs you the responsive renditions. AvatarImg receives an already-normalised src; see normalizeAvatarUrl.

The same type is also exported as TweetComponents, which is deprecated and kept only so code written against upstream keeps compiling. Use TwitterComponents.

For example, to replace the default img tag used for the avatar and media with next/image you can do the following:

// tweet-components.tsx
import Image from 'next/image'
import type { TwitterComponents } from 'react-x-embed'
 
export const components: TwitterComponents = {
  AvatarImg: (props) => <Image {...props} />,
  MediaImg: (props) => <Image {...props} fill unoptimized />,
}

And then pass the components to Tweet or EmbeddedTweet:

import { components } from './tweet-components'
 
const MyTweet = ({ id }: { id: string }) => (
  <Tweet id={id} components={components} />
)