OgCard – Once UI

The OgCard component displays rich link previews for URLs by fetching and rendering Open Graph metadata. It's perfect for showcasing external links with preview images, titles, and descriptions.

OgCard

<OgCard 
  url="https://once-ui.com"
/>

Mock data

Instead of fetching Open Graph data from a URL, you can directly provide the data to display.

Mock data

<OgCard 
  title="Design Engineers Club"
  description="The Design Engineers Club is a community of vibe coders."
  image="/images/docs/once-ui/vibe-coding-dark.jpg"
  favicon="/images/avatar.jpg"
  url="https://designengineers.club"
/>

Direction

The OgCard component supports different layout directions.

Direction

<OgCard 
  url="https://once-ui.com/about"
  direction="row"
/>

<OgCard 
  url="https://once-ui.com/products"
  direction="row-reverse"
/>

Size

The OgCard component supports different sizes.

Size

<OgCard 
  size="s"
  url="https://once-ui.com/about"
/>
<OgCard 
  size="m"
  url="https://once-ui.com/products"
/>
<OgCard 
  size="l"
  url="https://once-ui.com/customize"
/>

Conditional rendering

You can hide each element of the OgCard component by setting its prop value to false.

Conditional rendering

<OgCard 
  description={false}
  url="https://once-ui.com/about"
/>

Custom style

The OgCard extends the Card component, so you can use all Card props to customize its appearance.

Custom style

<OgCard 
  url="https://once-ui.com/customize"
  direction="column"
  background="brand-alpha-weak"
  border="brand-alpha-medium"
  shadow="l"
/>

Required API routes

To use OgCard with automatic Open Graph fetching, your application must expose the following API routes. These routes are used internally by the component to fetch metadata and safely load external assets.

1. OG metadata fetch

/api/og/fetch This endpoint retrieves Open Graph metadata (title, description, image, favicon) from a given URL. It is used when OgCard receives only a url prop. You can refer to the implementation in:

handleOGFetch.mdx

2. OG image proxy

/api/og/proxy This endpoint proxies external images to avoid CORS restrictions when rendering preview images inside the card. You can refer to the implementation in:

handleOGProxy.mdx

3. (Optional) OG generate endpoint

/api/og/generate Used in advanced setups where OG images are dynamically generated server-side. This is optional depending on your configuration.

Service configuration

Use serviceConfig to point OgCard at custom API routes or to transform proxied image and favicon URLs. Pass pre-fetched data with ogData to skip the fetch entirely.

Service configuration

<OgCard
url="https://example.com"
serviceConfig={{
  fetchOgUrl: '/api/og/fetch',
  proxyOgUrl: '/api/og/proxy',
  proxyImageUrl: (url) => `/api/og/proxy?url=${encodeURIComponent(url)}`,
  proxyFaviconUrl: (url) => `/api/og/proxy?url=${encodeURIComponent(url)}`,
}}
/>

<OgCard
ogData={{
  url: 'https://example.com',
  title: 'Example',
  description: 'Pre-fetched metadata',
  image: 'https://example.com/og.png',
  faviconUrl: 'https://example.com/favicon.ico',
}}
/>

API reference

Prop	Type	Default
url The page to preview. Its Open Graph data is fetched and rendered.	string	—
sizes The sizes attribute for the preview image.	string	320px
unoptimized Skip the framework image optimizer.	boolean	false
size Card scale.	lms	m
ogData Supply the data yourself instead of fetching it.	Partial<OgData>null	—
direction Image above the text, or beside it.	columnrowcolumn-reverserow-reverse	column
serviceConfig Where to fetch the Open Graph data from.	OgServiceConfig	{}
title Override the fetched title, or false to hide it.	stringfalse	—
description Override the fetched description, or false to hide it.	stringfalse	—
favicon Override the fetched favicon, or false to hide it.	stringfalse	—
image Override the fetched image, or false to hide it.	stringfalse	—
cardUrl Override the displayed link text, or false to hide it.	stringfalse	—
…and every FlexProps prop	inherited	—
…and every CardProps prop	inherited	—

OgServiceConfig

Prop	Type	Default
fetchOgUrl Endpoint for fetching OG metadata.	string	'/api/og/fetch'
proxyOgUrl Endpoint for proxying external assets.	string	'/api/og/proxy'
proxyImageUrl Transform OG image URLs before rendering.	(url: string) => string	—
proxyFaviconUrl Transform favicon URLs before rendering.	(url: string) => string	—

Notes

The component automatically fetches favicons for the domain
Images are proxied through an API endpoint to avoid CORS issues
You can overwrite the default props by providing static values
You can set any value to false to disable it