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 two routes: one that fetches a page's metadata, and one that serves its image from your origin. In a Next.js app, both are ready-made in @once-ui-system/core/next, with SSRF protection built in:

import { createOgFetchRoute } from "@once-ui-system/core/next";

export const { GET } = createOgFetchRoute();

See OG route handlers for their options. Outside Next.js, build the routes on handleOGFetch and handleOGProxy.

OgCard calls /api/og/fetch and /api/og/proxy by default. If your routes live elsewhere, wrap the app in OgRoutesProvider:

Custom routes

<OgRoutesProvider routes={{ fetch: "/og/fetch", proxy: "/og/proxy" }}>
{children}
</OgRoutesProvider>

The optional /api/og/generate route renders social images for Meta.generate; it is not needed by OgCard.

Service configuration

Use serviceConfig to point a single OgCard at custom API routes (it takes precedence over OgRoutesProvider) 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

	Type	Default
url The page to preview. Its Open Graph data is fetched and rendered.	string	—
sizes The sizes attribute for the preview image.	stringnumber	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

	Type	Default
fetchOgUrl Endpoint for fetching OG metadata.	string	OgRoutesProvider's fetch, or '/api/og/fetch'
proxyOgUrl Endpoint for proxying external assets.	string	OgRoutesProvider's proxy, or '/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