Getting Started with getCldOgImageUrl

The getCldOgImageUrl function helps you easily generate Social Card image URLs (Open Graph Images) using Cloudinary.

This URL can be then used when defining metadata for your page within Next.js.

Basic Usage

getCldOgImageUrl makes it convenient to create Social Card URLs out-of-the-box.

The only needed prop is src:

Note: The image above is rendered using the CldImage component for preview only.

import { getCldOgImageUrl } from 'next-cloudinary';
 
const url = getCldOgImageUrl({
  src: '<Public ID>'
});

The function simply returns a URL for the image public ID provided including default configurations including a standard width and height.

To use this in a Next.js app with the App Router, you would then configure it with your Metadata object or generate function:

import { Metadata } from 'next';
import { getCldOgImageUrl } from 'next-cloudinary';
 
const url = getCldOgImageUrl({
  src: '<Public ID>'
});
 
export const metadata: Metadata = {
  openGraph: {
    images: [
      {
        width: 1200,
        height: 627,
        url
      }
    ]
  }
}

Learn more about Next.js Metadata (opens in a new tab).

getCldOgImageUrl is a deritive of getCldImageUrl meaning it generally has the same API, but provides a few defaults for Open Graph images like sizes.

Image Size

By default, the image canvas is based upon 2400x1254, but resized down to 1200x627, meaning, you can design the image as if it were a 2400x1254 image, but the resulting image will be sized down to 1200x627 to avoid an overly large image.

627 (with a canvas of 1254) is used to satisfy the 1.91:1 ratio requirement and minimum size requirement from linkedin (opens in a new tab).

This two-step sizing is done to help maintain a consistent canvas size when designing elements such as overlays that require position and sizing relative to the original image.

You can use the width and the height to control the canvas and widthResize to change the final size the image is scaled to.

The height is ultimately calculated using the width value and the widthResize values to maintain the correct ratio.

Image Format

While Cloudinary's f_auto parameter (format of auto (opens in a new tab)) is great for websites and mobile apps, having more control over the format helps to reduce initial encoding time, which is more critical for a social network to recognize the image and load it on first share.

The safe default format for most use cases is then jpg, as webp does not have broad support (likely nor does AVIF).

Read more about webp support: https://www.ctrl.blog/entry/webp-ogp.html (opens in a new tab)

If you have the control in your application to produce multiple image sources, such has having a separate og:image and twitter:image, you can generate two (or more) URLs to produce as optimized a format as you can for the platform:

import { Metadata } from 'next';
import { getCldOgImageUrl } from 'next-cloudinary';
 
const ogImageUrl = getCldOgImageUrl({
  ...options,
  format: 'jpg',
});
 
const twitterImageUrl = getCldOgImageUrl({
  ...options,
  format: 'webp',
});
 
export const metadata: Metadata = {
  openGraph: {
    images: [
      {
        width: 1200,
        height: 627,
        url: ogImageUrl
      }
    ]
  },
  twitter: {
    images: [twitterImageUrl],
  },
}

Find out how else you can customize your Cloudinary image over on getCldOgImageUrl configuration.

Learn More about getCldOgImageUrl

• Configuration
• Examples