Package Exports

@framer-framer/react
@framer-framer/react/server

Readme

@framer-framer/react

React component for framer-framer — embed any URL with <Embed url="..." />.

Installation

npm install @framer-framer/react framer-framer react react-dom

Quick Start

import { Embed } from '@framer-framer/react';

function App() {
  return <Embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" />;
}

API

`<Embed />` Component

Prop	Type	Description
`url`	`string`	(required) URL to embed
`maxWidth`	`number`	Max embed width in pixels
`maxHeight`	`number`	Max embed height in pixels
`embedOptions`	`EmbedOptions`	Options passed to `embed()`
`initialData`	`EmbedResult`	Pre-fetched embed data (skips client-side fetch)
`onLoad`	`(result: EmbedResult) => void`	Called on successful resolution
`onError`	`(error: Error) => void`	Called on resolution failure
`loadingFallback`	`ReactNode`	Custom loading component
`errorFallback`	`ReactNode \| (error: Error) => ReactNode`	Custom error component
`className`	`string`	CSS class for the container
`style`	`CSSProperties`	Inline styles for the container
`ref`	`Ref<HTMLDivElement>`	Forwarded ref to container div

`useEmbed()` Hook

import { useEmbed } from '@framer-framer/react';

function MyEmbed({ url }: { url: string }) {
  const { status, data, error } = useEmbed(url, { maxWidth: 600 });

  if (status === 'loading') return <p>Loading...</p>;
  if (status === 'error') return <p>Error: {error.message}</p>;
  return <div dangerouslySetInnerHTML={{ __html: data.html }} />;
}

`<Skeleton />` and `<ErrorState />`

Built-in UI components used by <Embed /> internally. You can import them for custom compositions:

import { Skeleton, ErrorState } from '@framer-framer/react';

SSR / React Server Components

Server Component (`EmbedServer`)

Use EmbedServer from the /server export to fetch embed data entirely on the server — no client-side JavaScript required:

// app/page.tsx (Next.js App Router - Server Component)
import { EmbedServer } from '@framer-framer/react/server';

export default async function Page() {
  return <EmbedServer url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" />;
}

EmbedServer is an async component that calls embed() on the server and renders the resulting HTML directly. It does not include "use client" and ships zero client-side JavaScript.

Prop	Type	Description
`url`	`string`	(required) URL to embed
`maxWidth`	`number`	Max embed width in pixels
`maxHeight`	`number`	Max embed height in pixels
`embedOptions`	`EmbedOptions`	Options passed to `embed()`
`errorFallback`	`ReactNode \| (error: Error) => ReactNode`	Custom error component
`className`	`string`	CSS class for the container
`style`	`CSSProperties`	Inline styles for the container
`theme`	`'light' \| 'dark' \| 'auto'`	Theme mode (default: `'auto'`)

Server-fetched data with Client Component (`initialData`)

Fetch data on the server and pass it to the client <Embed /> via initialData to avoid a loading flash while retaining client-side interactivity (callbacks, ref, etc.):

// app/page.tsx (Server Component)
import { embed } from 'framer-framer';
import { EmbedSection } from './EmbedSection';

export default async function Page() {
  const data = await embed('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
  return <EmbedSection url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" initialData={data} />;
}

// app/EmbedSection.tsx (Client Component)
'use client';
import { Embed } from '@framer-framer/react';
import type { EmbedResult } from 'framer-framer';

export function EmbedSection({ url, initialData }: { url: string; initialData: EmbedResult }) {
  return <Embed url={url} initialData={initialData} onLoad={(r) => console.log(r.title)} />;
}

Client-only (default)

The main export uses the "use client" directive. During SSR it renders the skeleton placeholder; the embed resolves client-side after hydration via useEffect.

Examples

Custom Loading & Error

<Embed
  url="https://x.com/jack/status/20"
  loadingFallback={<MySpinner />}
  errorFallback={(err) => <p>Could not load: {err.message}</p>}
/>

With Callbacks

<Embed
  url="https://vimeo.com/1084537"
  onLoad={(result) => console.log('Loaded:', result.title)}
  onError={(err) => console.error('Failed:', err)}
/>

Next.js App Router

// app/page.tsx — fully server-rendered, zero client JS
import { EmbedServer } from '@framer-framer/react/server';

export default async function Page() {
  return <EmbedServer url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" maxWidth={800} />;
}

License

MIT