🚀 DAY 5 OF LAUNCH WEEK:Introducing Webhook Events for Alert Changes.Learn more →
Socket
Book a DemoInstallSign in
Socket
Book a DemoInstallSign in

eleventy-plugin-og-image

Package Overview
Dependencies
Maintainers
1
Versions
45
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

eleventy-plugin-og-image

A plugin to create Open Graph Images from JSX for Eleventy.

latest
Source
npmnpm
Version
4.2.1
Version published
Maintainers
1
Created
Source

Eleventy Plugin OG Image npm

This plugin helps to create Open Graph images in Eleventy using HTML1 within any supported template language and CSS2 via satori. No headless browser will be harmed 😉.

Usage

Install the package:

npm install eleventy-plugin-og-image --save-dev

ESM

It's preferred to use this plugin within ESM Eleventy projects. Read more about ESM vs CommonJS on the Eleventy documentation.

import EleventyPluginOgImage from 'eleventy-plugin-og-image';

export default async function (eleventyConfig) {
  eleventyConfig.addPlugin(EleventyPluginOgImage, {
    satoriOptions: {
      fonts: [
        {
          name: 'Inter',
          data: fs.readFileSync('../path/to/font-file/inter.woff'),
          weight: 700,
          style: 'normal',
        },
      ],
    },
  });
}

CommonJS

[!NOTE] This plugin is written in ESM, therefore require is not possible. If the .eleventy.js config uses CommonJS, switch to async and create a dynamic import as shown below.

module.exports = async function (eleventyConfig) {
  const EleventyPluginOgImage = (await import('eleventy-plugin-og-image')).default;

  eleventyConfig.addPlugin(EleventyPluginOgImage, {
    // See above for example config
  });
};

Add a Template

Create an OG-image-template anywhere in the input directory. Use only the supported HTML elements1 and CSS properties2. CSS in <style> tags will be inlined, remote images fetched. Shortcode scoped data from the parent template is available. Additionally, some options will be available in the eleventyPluginOgImage key. This is an example og-image.og.njk:

<style>
  .root {
    width: 100%;
    height: 100%;
    display: flex;
    flex-direction: column;
    align-items: center;
    background: linear-gradient(135deg, #ef629f, #eecda3);
  }

  .title {
    color: white;
    font-size: 80px;
    margin: auto 0;
  }
</style>

<div class="root">
  <h1 class="title">{{ title }}</h1>
</div>

Call the ogImage shortcode inside the <head> in a template or layout. The first argument is the filePath of the OG-image-template (required, relative to the Eleventy input directory). The second argument is for data (optional). Usage example in Nunjucks, e.g. example-page.njk:

{% ogImage "./og-image.og.njk", { title: "Hello World!" } %}

Result

Generated OG image _site/og-images/s0m3h4sh.png:

Generated OG image

HTML output generated by the shortcode into _site/example-page/index.html (can be modified via the shortcodeOutput option):

<meta property="og:image" content="/og-images/s0m3h4sh.png" />

For applied usage see the example.

[!TIP] The template language of the page and OG-image-template can be mixed or matched.

Configuration

The following options can be passed when adding the plugin:

PropertyTypeDefault
inputFileGlobglob**/*.og.*This must match the OG-image-templates to prevent HTML compilation.
hashLengthnumber8
outputFileExtensionsharp output file formatspng
outputDirstringog-imagesDirectory into which OG images will be emitted. Relative to eleventy output.
previewModeauto | booleanautoEnable/disable preview mode.
previewDirstring${outputDir}/previewDirectory used for preview during watch or serve. Relative to eleventy output.
urlPathstring${outputDir}URL-prefix which will be used in returned meta-tags.
outputFileSlugfunctionSee sourceGeneration of the output file slug, must be url safe and exclude the file extension.
shortcodeOutputfunctionSee sourceChange the HTML returned by the shortcode in pages.
satoriOptionssatori options{ width: 1200, height: 630, fonts: [] }If an OG-image-template contains text, it's required to load a font (example).
sharpOptionssharp output optionsundefinedOptions must be corresponding to chosen outputFileExtension.
OgImageclass CustomOgImage extends OgImageOgImageExtend the OgImage class for maximum customization.

Preview Mode

The previewMode is intended to ease the styling of OG images. When previewMode is set to auto (default) the OG images are also copied into the previewDir during development with watch or serve. The files are named by the url slug of the pages they are generated from. Next to it there is a HTML placed which shows the generated HTML, SVG and output image. The previewDir will be deleted during a production build. When not actively working on OG images, performance can be improved by disabling previewMode.

Caching

For better performance OG images are cached based on a hash from generated HTML and output options. If the file already exists, further transformations are skipped.

Advanced Usage

Extending OgImage Class

It's possible to extend and overwrite any of the functions from the OgImage class. The custom class is passed as the OgImage parameter to the plugin.

import EleventyPluginOgImage from 'eleventy-plugin-og-image';
import { OgImage } from 'eleventy-plugin-og-image/og-image';

export class CustomOgImage extends BaseOgImage {
  async shortcodeOutput() {
    return this.outputUrl();
  }
}

/** @param {import('@11ty/eleventy/src/UserConfig').default} eleventyConfig */
export default async function (eleventyConfig) {
  eleventyConfig.addPlugin(EleventyPluginOgImage, {
    OgImage: CustomOgImage,
  });
}

Custom Shortcode

A custom shortcode can be created by using the OgImage class.

import { OgImage } from 'eleventy-plugin-og-image/og-image';

const image = await new OgImage({ inputPath, data, options, templateConfig }).render();

Capture Output URL

The plugins shortcode create a meta tag per default, modify the shortcodeOutput option or class function to directly return the outputUrl:

eleventyConfig.addPlugin(EleventyPluginOgImage, {
  async shortcodeOutput(ogImage) {
    return ogImage.outputUrl();
  },
});

Furthermore, it's possible to capture the outputUrl to a variable, e.g. in Nunjucks:

{% setAsync "ogOutputUrl" -%}
    {% ogImage "./og-image.og.njk", { title: "Hello World!" } %}
{%- endsetAsync %}

And use it anywhere afterward with {{ ogOutputUrl }}.

Acknowledgements & Attributions

This plugin is deeply inspired by @vercel/og.

Furthermore, it would not be possible without:

Footnotes

Keywords

11ty
eleventy
eleventy-plugin
og:image

FAQs

Package last updated on 30 Oct 2025

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

Introducing Webhook Events for Alert Changes

Product

Introducing Webhook Events for Alert Changes

Add real-time Socket webhook events to your workflows to automatically receive software supply chain alert changes in real time.

By Phil Gates-Idem  -  Nov 21, 2025
Introducing Socket Scanning for OpenVSX Extensions

Product

Introducing Socket Scanning for OpenVSX Extensions

Socket now scans OpenVSX extensions, giving teams early detection of risky behaviors, hidden capabilities, and supply chain threats in developer tools.

By Mix Irving, Ryan Eberhardt  -  Nov 20, 2025