useOgData

The useOgData hook fetches Open Graph metadata from URLs, including title, description, image, and favicon. It automatically handles image proxying for external sources and provides loading states. Used in components: OGCard

Most of the time you don't need to use this hook directly. The OGCard component already uses it internally to fetch and display Open Graph previews. Use this hook when you need custom rendering or additional control over the fetching logic.

Features

Fetches OG metadata from any URL
Automatic image proxying for CORS-free display
Loading state management
Custom API endpoint support
Companion useOgImage hook for image-only fetching

Basic usage

Fetch and display Open Graph data:

LinkPreview.tsx

import { useOgData } from '@once-ui-system/core';

function LinkPreview({ url }: { url: string }) {
const { ogData, loading } = useOgData(url);

if (loading) return <div>Loading preview...</div>;
if (!ogData) return null;

return (
  <div>
    {ogData.image && <img src={ogData.image} alt={ogData.title} />}
    <h3>{ogData.title}</h3>
    <p>{ogData.description}</p>
    <a href={ogData.url}>Visit site</a>
  </div>
);
}

With custom endpoints

Use custom API routes for fetching and proxying:

CustomLinkPreview.tsx

import { useOgData } from '@once-ui-system/core';

function CustomLinkPreview({ url }: { url: string }) {
const { ogData, loading } = useOgData(
  url,
  '/api/custom/fetch',  // Custom fetch endpoint
  '/api/custom/proxy'   // Custom proxy endpoint
);

return (
  <div>
    {loading ? (
      <Skeleton />
    ) : (
      <Card>
        <img src={ogData?.image} alt={ogData?.title} />
        <h3>{ogData?.title}</h3>
        <p>{ogData?.description}</p>
      </Card>
    )}
  </div>
);
}

useOgImage hook

For cases where you only need the image:

LinkThumbnail.tsx

import { useOgImage } from '@once-ui-system/core';

function LinkThumbnail({ url }: { url: string }) {
const { ogImage, loading } = useOgImage(url);

if (loading) return <Skeleton width={200} size={200} />;
if (!ogImage) return <DefaultThumbnail />;

return (
  <img
    src={ogImage}
    alt="Link thumbnail"
    width={200}
    height={200}
  />
);
}

With OGCard component

Combine with the OGCard component for rich previews:

RichLinkPreview.tsx

import { OGCard } from '@once-ui-system/core';

function RichLinkPreview({ url }: { url: string }) {
return (
  <OGCard
    url={url}
    aspectRatio="16 / 9"
    radius="l"
    border="neutral-medium"
  />
);
}

API Reference

Prop	Type	Default
url	stringnull	—
customFetchUrl	string	'/api/og/fetch'
customProxyUrl	string	'/api/og/proxy'

Return value

Return type

interface OgData {
title: string;
description: string;
image: string;
url: string;
faviconUrl?: string;
}

{
ogData: Partial<OgData> | null;
loading: boolean;
}

useOgImage

Prop	Type	Default
url	stringnull	—
customFetchUrl	string	'/api/og/fetch'
customProxyUrl	string	'/api/og/proxy'

useOgImage return value

Return type

{
ogImage: string | null;
loading: boolean;
}

Required API routes

This hook requires server-side API routes to function. Use the handleOGFetch and handleOGProxy utilities:

API routes

// app/api/og/fetch/route.ts
import { handleOGFetch } from '@once-ui-system/core/server';

export async function GET(request: Request) {
return handleOGFetch(request);
}

// app/api/og/proxy/route.ts
import { handleOGProxy } from '@once-ui-system/core/server';

export async function GET(request: Request) {
return handleOGProxy(request);
}

Image proxying

The hook automatically proxies external images through your server to avoid CORS issues:

Images from the same origin are used directly
External images are routed through the proxy endpoint
The proxy adds appropriate cache headers

Error handling

The hook handles errors gracefully:

SafeLinkPreview.tsx

function SafeLinkPreview({ url }: { url: string }) {
const { ogData, loading } = useOgData(url);

if (loading) return <Skeleton />;

if (!ogData) {
  return (
    <div>
      <p>Unable to load preview</p>
      <a href={url}>{url}</a>
    </div>
  );
}

return <OGCard url={url} />;
}

Performance tips

Conditional fetching: Pass null as URL to skip fetching
Memoize URLs: Prevent unnecessary refetches
Cache responses: The proxy endpoint includes cache headers

OptimizedPreview.tsx

import { useMemo } from 'react';
import { useOgData } from '@once-ui-system/core';

function OptimizedPreview({ rawUrl }: { rawUrl: string | undefined }) {
// Only fetch when URL is valid
const url = useMemo(() => {
  try {
    return rawUrl ? new URL(rawUrl).href : null;
  } catch {
    return null;
  }
}, [rawUrl]);

const { ogData, loading } = useOgData(url);

if (!url) return <div>Invalid URL</div>;
if (loading) return <Skeleton />;

return <OGCard url={url} />;
}