6.5.0 • Published 1 month ago

next-seo v6.5.0

Weekly downloads
77,006
License
MIT
Repository
github
Last release
1 month ago

Have you seen the new Next.js newsletter?

Next SEO

npm

Next SEO is a plugin that makes managing your SEO easier in Next.js projects.

Pull requests are very welcome. Also make sure to check out the issues for feature requests if you are looking for inspiration on what to add.

Feel like supporting this free plugin?

It takes a lot of time to maintain an open source project so any small contribution is greatly appreciated.

Coffee fuels coding ☕️

next-seo.wallet (ERC20 & SOL)

Note on app directory

This note is only relevant if using the app directory.

For standard meta data (eg: , ) then it is highly recommended that you use the built in generateMetaData method. You can check out the docs here

For JSON-LD then the only change needed is you should add useAppDir={true} to the JSON-LD component in use. You should add use this component in your page.js and NOT your head.js.

<ArticleJsonLd
  useAppDir={true}
  url="https://example.com/article"
  title="Article headline" <- required for app directory
  />

If you are using pages directory then NextSeo is exactly what you need for your SEO needs!

Table of Contents

Usage

NextSeo works by including it on pages where you would like SEO attributes to be added. Once included on the page you pass it a configuration object with the page's SEO properties. This can be dynamically generated at a page level or in some cases your API may return an SEO object.

Setup

First, install it:

npm install next-seo

or

yarn add next-seo

Add SEO to Page


Using Next.js app directory introduced in Next.js 13?

If you are using Next.js app directory then it is highly recommended that you use the built in generateMetaData method. You can check out the docs here

If you are using pages directory then NextSeo is exactly what you need for your SEO needs!


Then you need to import NextSeo and add the desired properties. This will render out the tags in the <head> for SEO. At a bare minimum, you should add a title and description.

Example with just title and description:

import { NextSeo } from 'next-seo';

const Page = () => (
  <>
    <NextSeo
      title="Simple Usage Example"
      description="A short description goes here."
    />
    <p>Simple Usage</p>
  </>
);

export default Page;

But NextSeo gives you many more options that you can add. See below for a typical example of a page.

Typical page example:

import { NextSeo } from 'next-seo';

const Page = () => (
  <>
    <NextSeo
      title="Using More of Config"
      description="This example uses more of the available config options."
      canonical="https://www.canonical.ie/"
      openGraph={{
        url: 'https://www.url.ie/a',
        title: 'Open Graph Title',
        description: 'Open Graph Description',
        images: [
          {
            url: 'https://www.example.ie/og-image-01.jpg',
            width: 800,
            height: 600,
            alt: 'Og Image Alt',
            type: 'image/jpeg',
          },
          {
            url: 'https://www.example.ie/og-image-02.jpg',
            width: 900,
            height: 800,
            alt: 'Og Image Alt Second',
            type: 'image/jpeg',
          },
          { url: 'https://www.example.ie/og-image-03.jpg' },
          { url: 'https://www.example.ie/og-image-04.jpg' },
        ],
        siteName: 'SiteName',
      }}
      twitter={{
        handle: '@handle',
        site: '@site',
        cardType: 'summary_large_image',
      }}
    />
    <p>SEO Added to Page</p>
  </>
);

export default Page;

A note on Twitter Tags

Props cardType, site, handle are equivalent to twitter:card, twitter:site, twitter:creator. Documentation can be found here.

Twitter will read the og:title, og:image and og:description tags for their card. next-seo omits twitter:title, twitter:image and twitter:description to avoid duplication.

Some tools may report this an error. See Issue #14

Default SEO Configuration

NextSeo enables you to set some default SEO properties that will appear on all pages without needing to include anything on them. You can also override these on a page by page basis if needed.

To achieve this, you will need to create a custom <App>. In your pages directory create a new file, _app.js. See the Next.js docs here for more info on a custom <App>.

Within this file you will need to import DefaultSeo from next-seo and pass it props.

Here is a typical example:

import App, { Container } from 'next/app';
import { DefaultSeo } from 'next-seo';

// import your default seo configuration
import SEO from '../next-seo.config';

export default class MyApp extends App {
  render() {
    const { Component, pageProps } = this.props;
    return (
      <Container>
        <DefaultSeo
          openGraph={{
            type: 'website',
            locale: 'en_IE',
            url: 'https://www.url.ie/',
            siteName: 'SiteName',
          }}
          twitter={{
            handle: '@handle',
            site: '@site',
            cardType: 'summary_large_image',
          }}
        />
        <Component {...pageProps} />
      </Container>
    );
  }
}

To work properly, DefaultSeo should be placed above (before) Component due to behavior of Next.js internals.

Alternatively, you can also create a config file to store default values such as next-seo.config.js

export default {
  openGraph: {
    type: 'website',
    locale: 'en_IE',
    url: 'https://www.url.ie/',
    siteName: 'SiteName',
  },
  twitter: {
    handle: '@handle',
    site: '@site',
    cardType: 'summary_large_image',
  },
};
import { DefaultSeoProps } from 'next-seo';

const config: DefaultSeoProps = {
  openGraph: {
    type: 'website',
    locale: 'en_IE',
    url: 'https://www.url.ie/',
    siteName: 'SiteName',
  },
  twitter: {
    handle: '@handle',
    site: '@site',
    cardType: 'summary_large_image',
  },
};

export default config;

import at the top of _app.js

import SEO from '../next-seo.config';

and the DefaultSeo component can be used like this instead

<DefaultSeo {...SEO} />

From now on all of your pages will have the defaults above applied.

Note that Container is deprecated in Next.js v9.0.4 so you should replace that component here with React.Fragment on this version and later - see here

NextSeo Options

PropertyTypeDescription
titleTemplatestringAllows you to set default title template that will be added to your title More Info
titlestringSet the meta title of the page
defaultTitlestringIf no title is set on a page, this string will be used instead of an empty titleTemplate More Info
noindexboolean (default false)Sets whether page should be indexed or not More Info
nofollowboolean (default false)Sets whether page should be followed or not More Info
robotsPropsObjectSet the more meta information for the X-Robots-Tag More Info
descriptionstringSet the page meta description
canonicalstringSet the page canonical url
mobileAlternate.mediastringSet what screen size the mobile website should be served from
mobileAlternate.hrefstringSet the mobile page alternate url
languageAlternatesarraySet the language of the alternate urls. Expects array of objects with the shape: { hrefLang: string, href: string }
themeColorstringIndicates a suggested color that user agents should use to customize the display of the page or of the surrounding user interface. Must contain a valid CSS color
additionalMetaTagsarrayAllows you to add a meta tag that is not documented here. More Info
additionalLinkTagsarrayAllows you to add a link tag that is not documented here. More Info
twitter.cardTypestringThe card type, which will be one of summary, summary_large_image, app, or player
twitter.sitestring@username for the website used in the card footer
twitter.handlestring@username for the content creator / author (outputs as twitter:creator)
facebook.appIdstringUsed for Facebook Insights, you must add a facebook app ID to your page to for it More Info
openGraph.urlstringThe canonical URL of your object that will be used as its permanent ID in the graph
openGraph.typestringThe type of your object. Depending on the type you specify, other properties may also be required More Info
openGraph.titlestringThe open graph title, this can be different than your meta title.
openGraph.descriptionstringThe open graph description, this can be different than your meta description.
openGraph.imagesarrayAn array of images (object) to be used by social media platforms, slack etc as a preview. If multiple supplied you can choose one when sharing. See Examples
openGraph.videosarrayAn array of videos (object)
openGraph.localestringThe locale the open graph tags are marked up in. Of the format language_TERRITORY. Default is en_US.
openGraph.siteNamestringIf your object is part of a larger web site, the name which should be displayed for the overall site.
openGraph.profile.firstNamestringPerson's first name.
openGraph.profile.lastNamestringPerson's last name.
openGraph.profile.usernamestringPerson's username.
openGraph.profile.genderstringPerson's gender.
openGraph.book.authorsstring[]Writers of the article. See Examples
openGraph.book.isbnstringThe ISBN
openGraph.book.releaseDatedatetimeThe date the book was released.
openGraph.book.tagsstring[]Tag words associated with this book.
openGraph.article.publishedTimedatetimeWhen the article was first published. See Examples
openGraph.article.modifiedTimedatetimeWhen the article was last changed.
openGraph.article.expirationTimedatetimeWhen the article is out of date after.
openGraph.article.authorsstring[]Writers of the article.
openGraph.article.sectionstringA high-level section name. E.g. Technology
openGraph.article.tagsstring[]Tag words associated with this article.

Title Template

Replaces %s with your title string

title = 'This is my title';
titleTemplate = 'Next SEO | %s';
// outputs: Next SEO | This is my title
title = 'This is my title';
titleTemplate = '%s | Next SEO';
// outputs: This is my title | Next SEO

Default Title

title = undefined;
titleTemplate = 'Next SEO | %s';
defaultTitle = 'Next SEO';
// outputs: Next SEO

No Index

Setting this to true will set noindex,follow (to set nofollow, please refer to nofollow). This works on a page by page basis. This property works in tandem with the nofollow property and together they populate the robots meta tag.

Note: The noindex and the nofollow properties are a little different than all the others in the sense that setting them as a default does not work as expected. This is due to the fact Next SEO already has a default of index,follow because next-seo is a SEO plugin after all. So if you want to globally these properties, please see dangerouslySetAllPagesToNoIndex and dangerouslySetAllPagesToNoFollow.

Example No Index on a single page:

If you have a single page that you want no indexed you can achieve this by:

import { NextSeo } from 'next-seo';

const Page = () => (
  <>
    <NextSeo noindex={true} />
    <p>This page is no indexed</p>
  </>
);

export default Page;

/*
<meta name="robots" content="noindex,follow">
*/

dangerouslySetAllPagesToNoIndex

It has the prefix of dangerously because it will noindex all pages. As this is an SEO plugin, that is kinda dangerous action. It is not bad to use this, just please be sure you want to noindex EVERY page. You can still override this at a page level if you have a use case to index a page. This can be done by setting noindex: false.

The only way to unset this, is by removing the prop from the DefaultSeo in your custom <App>.

No Follow

Setting this to true will set index,nofollow (to set noindex, please refer to noindex). This works on a page by page basis. This property works in tandem with the noindex property and together they populate the robots meta tag.

Note: Unlike for the other properties, setting noindex and nofollow by default does not work as expected. This is because Next SEO has a default of index,follow, since next-seo is an SEO plugin after all. If you want to globally allow these properties, see dangerouslySetAllPagesToNoIndex and dangerouslySetAllPagesToNoFollow.

Example No Follow on a single page:

If you have a single page that you want no indexed you can achieve this by:

import { NextSeo } from 'next-seo';

const Page = () => (
  <>
    <NextSeo nofollow={true} />
    <p>This page is not followed</p>
  </>
);

export default Page;

/*
<meta name="robots" content="index,nofollow">
*/

dangerouslySetAllPagesToNoFollow

It has the prefix of dangerously because it will nofollow all pages. As this is an SEO plugin, that is kinda dangerous action. It is not bad to use this, just please be sure you want to nofollow EVERY page. You can still override this at a page level if you have a use case to follow a page. This can be done by setting nofollow: false.

The only way to unset this, is by removing the prop from the DefaultSeo in your custom <App>.

noindexnofollowmeta content of robots
----index,follow (default)
falsefalseindex,follow
true--noindex,follow
truefalsenoindex,follow
--trueindex,nofollow
falsetrueindex,nofollow
truetruenoindex,nofollow

robotsProps

In addition to index, follow the robots meta tag accepts more properties to archive a more accurate crawling and serve better snippets for SEO bots that crawl your page.

Example:

import { NextSeo } from 'next-seo';

const Page = () => (
  <>
    <NextSeo
      robotsProps={{
        nosnippet: true,
        notranslate: true,
        noimageindex: true,
        noarchive: true,
        maxSnippet: -1,
        maxImagePreview: 'none',
        maxVideoPreview: -1,
      }}
    />
    <p>Additional robots props in Next-SEO!!</p>
  </>
);

export default Page;

/*
<meta name="robots" content="index,follow,nosnippet,max-snippet:-1,max-image-preview:none,noarchive,noimageindex,max-video-preview:-1,notranslate">
*/

Available properties

PropertyTypeDescription
noarchivebooleanDo not show a cached link in search results.
nosnippetbooleanDo not show a text snippet or video preview in the search results for this page.
max-snippetnumberUse a maximum of number characters as a textual snippet for this search result. Read more
max-image-preview'none','standard','large'Set the maximum size of an image preview for this page in a search results.
max-video-previewnumberUse a maximum of number seconds as a video snippet for videos on this page in search results. Read more
notranslatebooleanDo not offer translation of this page in search results.
noimageindexbooleanDo not index images on this page.
unavailable_afterstringDo not show this page in search results after the specified date/time. The date/time must be specified in a widely adopted format including, but not limited to RFC 822, RFC 850, and ISO 8601.

For more reference about the X-Robots-Tag visit Google Search Central - Control Crawling and Indexing

Twitter

Twitter will read the og:title, og:image and og:description tags for their card, this is why next-seo omits twitter:title, twitter:image and twitter:description so not to duplicate.

Some tools may report this an error. See Issue #14

facebook

facebook={{
  appId: '1234567890',
}}

Add this to your SEO config to include the fb:app_id meta if you need to enable Facebook insights for your site. Information regarding this can be found in facebook's documentation

Canonical URL

Add this on a page per page basis when you want to consolidate duplicate URLs.

canonical = 'https://www.canonical.ie/';

Alternate

This link relation is used to indicate a relation between a desktop and a mobile website to search engines.

Example:

mobileAlternate={{
  media: 'only screen and (max-width: 640px)',
  href: 'https://m.canonical.ie',
}}
languageAlternates={[{
  hrefLang: 'de-AT',
  href: 'https://www.canonical.ie/de',
}]}

Additional Meta Tags

This allows you to add any other meta tags that are not covered in the config and should be used instead of children prop.

content is required. Then either name, property or httpEquiv. (Only one on each)

Example:

additionalMetaTags={[{
  property: 'dc:creator',
  content: 'Jane Doe'
}, {
  name: 'application-name',
  content: 'NextSeo'
}, {
  httpEquiv: 'x-ua-compatible',
  content: 'IE=edge; chrome=1'
}]}

Invalid Examples:

These are invalid as they contain more than one of name, property and httpEquiv on the same entry.

additionalMetaTags={[{
  property: 'dc:creator',
  name: 'dc:creator',
  content: 'Jane Doe'
}, {
  property: 'application-name',
  httpEquiv: 'application-name',
  content: 'NextSeo'
}]}

One thing to note on this is that it currently only supports unique tags, unless you use the keyOverride prop to provide a unique key to each additional meta tag.

The default behaviour (without a keyOverride prop) is to render one tag per unique name / property / httpEquiv. The last one defined will be rendered.

For example if you pass 2 tags with the same property:

additionalMetaTags={[{
  property: 'dc:creator',
  content: 'Joe Bloggs'
}, {
  property: 'dc:creator',
  content: 'Jane Doe'
}]}

it will result in this being rendered:

<meta property="dc:creator" content="Jane Doe" />

Providing an additional keyOverride property like this:

additionalMetaTags={[{
  property: 'dc:creator',
  content: 'Joe Bloggs',
  keyOverride: 'creator1',
}, {
  property: 'dc:creator',
  content: 'Jane Doe',
  keyOverride: 'creator2',
}]}

results in the correct HTML being rendered:

<meta property="dc:creator" content="Joe Bloggs" />
<meta property="dc:creator" content="Jane Doe" />

Additional Link Tags

This allows you to add any other link tags that are not covered in the config.

rel and href is required.

Example:

additionalLinkTags={[
  {
    rel: 'icon',
    href: 'https://www.test.ie/favicon.ico',
  },
  {
    rel: 'apple-touch-icon',
    href: 'https://www.test.ie/touch-icon-ipad.jpg',
    sizes: '76x76'
  },
  {
    rel: 'manifest',
    href: '/manifest.json'
  },
  {
    rel: 'preload',
    href: 'https://www.test.ie/font/sample-font.woof2',
    as: 'font',
    type: 'font/woff2',
    crossOrigin: 'anonymous'
  }
]}

it will result in this being rendered:

<link rel="icon" href="https://www.test.ie/favicon.ico" />
<link
  rel="apple-touch-icon"
  href="https://www.test.ie/touch-icon-ipad.jpg"
  sizes="76x76"
/>
<link rel="manifest" href="/manifest.json" />
<link
  rel="preload"
  href="https://www.test.ie/font/sample-font.woof2"
  as="font"
  type="font/woff2"
  crossorigin="anonymous"
/>

Open Graph

For the full specification please check out http://ogp.me/

Next SEO currently supports:

Open Graph Examples

Basic

import { NextSeo } from 'next-seo';

const Page = () => (
  <>
    <NextSeo
      openGraph={{
        type: 'website',
        url: 'https://www.example.com/page',
        title: 'Open Graph Title',
        description: 'Open Graph Description',
        images: [
          {
            url: 'https://www.example.ie/og-image.jpg',
            width: 800,
            height: 600,
            alt: 'Og Image Alt',
          },
          {
            url: 'https://www.example.ie/og-image-2.jpg',
            width: 800,
            height: 600,
            alt: 'Og Image Alt 2',
          },
        ],
      }}
    />
    <p>Basic</p>
  </>
);

export default Page;

Note

Multiple images is available from next.js version 7.0.0-canary.0

For versions 6.0.0 - 7.0.0-canary.0 you just need to supply a single item array:

images: [
  {
    url: 'https://www.example.ie/og-image-01.jpg',
    width: 800,
    height: 600,
    alt: 'Og Image Alt',
  },
],

Supplying multiple images will not break anything, but only one will be added to the head.

Video

Full info on http://ogp.me/

import { NextSeo } from 'next-seo';

const Page = () => (
  <>
    <NextSeo
      title="Video Page Title"
      description="Description of video page"
      openGraph={{
        title: 'Open Graph Video Title',
        description: 'Description of open graph video',
        url: 'https://www.example.com/videos/video-title',
        type: 'video.movie',
        video: {
          // Multiple Open Graph actors is only available in version `7.0.2-canary.35`+ of next
          actors: [
            {
              profile: 'https://www.example.com/actors/@firstnameA-lastnameA',
              role: 'Protagonist',
            },
            {
              profile: 'https://www.example.com/actors/@firstnameB-lastnameB',
              role: 'Antagonist',
            },
          ],
          // Multiple Open Graph directors is only available in version `7.0.2-canary.35`+ of next
          directors: [
            'https://www.example.com/directors/@firstnameA-lastnameA',
            'https://www.example.com/directors/@firstnameB-lastnameB',
          ],
          // Multiple Open Graph writers is only available in version `7.0.2-canary.35`+ of next
          writers: [
            'https://www.example.com/writers/@firstnameA-lastnameA',
            'https://www.example.com/writers/@firstnameB-lastnameB',
          ],
          duration: 680000,
          releaseDate: '2022-12-21T22:04:11Z',
          // Multiple Open Graph tags is only available in version `7.0.2-canary.35`+ of next
          tags: ['Tag A', 'Tag B', 'Tag C'],
        },
        siteName: 'SiteName',
      }}
    />
    <h1>Video Page SEO</h1>
  </>
);

export default Page;

Note

Multiple images is available from next.js version 7.0.0-canary.0

For versions 6.0.0 - 7.0.0-canary.0 you just need to supply a single item array:

images: [
  {
    url: 'https://www.example.ie/og-image-01.jpg',
    width: 800,
    height: 600,
    alt: 'Og Image Alt',
  },
],

Supplying multiple images will not break anything, but only one will be added to the head.

Audio

Full info on http://ogp.me/

import { NextSeo } from 'next-seo';
const Page = () => (
  <>
    <NextSeo
      title="Audio Page Title"
      description="Description of audio page"
      openGraph={{
        title: 'Open Graph Audio',
        description: 'Description of open graph audio',
        url: 'https://www.example.com/audio/audio',
        audio: [
          {
            url: 'http://examples.opengraphprotocol.us/media/audio/1khz.mp3',
            secureUrl: 'https://d72cgtgi6hvvl.cloudfront.net/media/audio/1khz.mp3',
            type: "audio/mpeg"
          },
          {
            url: 'http://examples.opengraphprotocol.us/media/audio/250hz.mp3',
            secureUrl: 'https://d72cgtgi6hvvl.cloudfront.net/media/audio/250hz.mp3',
            type: "audio/mpeg"
          },
        ]
        site_name: 'SiteName',
      }}
    />
    <h1>Audio Page SEO</h1>
  </>
);
export default Page;

Article

import { NextSeo } from 'next-seo';

const Page = () => (
  <>
    <NextSeo
      openGraph={{
        title: 'Open Graph Article Title',
        description: 'Description of open graph article',
        url: 'https://www.example.com/articles/article-title',
        type: 'article',
        article: {
          publishedTime: '2017-06-21T23:04:13Z',
          modifiedTime: '2018-01-21T18:04:43Z',
          expirationTime: '2022-12-21T22:04:11Z',
          section: 'Section II',
          authors: [
            'https://www.example.com/authors/@firstnameA-lastnameA',
            'https://www.example.com/authors/@firstnameB-lastnameB',
          ],
          tags: ['Tag A', 'Tag B', 'Tag C'],
        },
        images: [
          {
            url: 'https://www.test.ie/images/cover.jpg',
            width: 850,
            height: 650,
            alt: 'Photo of text',
          },
        ],
      }}
    />
    <p>Article</p>
  </>
);

export default Page;

Note

Multiple images, authors, tags is available from next.js version 7.0.0-canary.0

For versions 6.0.0 - 7.0.0-canary.0 you just need to supply a single item array:

images:

images: [
  {
    url: 'https://www.example.ie/og-image-01.jpg',
    width: 800,
    height: 600,
    alt: 'Og Image Alt',
  },
],

authors:

authors: [
  'https://www.example.com/authors/@firstnameA-lastnameA',
],

tags:

tags: ['Tag A'],

Supplying multiple of any of the above will not break anything, but only one will be added to the head.

Book

import { NextSeo } from 'next-seo';

const Page = () => (
  <>
    <NextSeo
      openGraph={{
        title: 'Open Graph Book Title',
        description: 'Description of open graph book',
        url: 'https://www.example.com/books/book-title',
        type: 'book',
        book: {
          releaseDate: '2018-09-17T11:08:13Z',
          isbn: '978-3-16-148410-0',
          authors: [
            'https://www.example.com/authors/@firstnameA-lastnameA',
            'https://www.example.com/authors/@firstnameB-lastnameB',
          ],
          tags: ['Tag A', 'Tag B', 'Tag C'],
        },
        images: [
          {
            url: 'https://www.test.ie/images/book.jpg',
            width: 850,
            height: 650,
            alt: 'Cover of the book',
          },
        ],
      }}
    />
    <p>Book</p>
  </>
);

export default Page;

Note

Multiple images, authors, tags is available from next.js version 7.0.0-canary.0

For versions 6.0.0 - 7.0.0-canary.0 you just need to supply a single item array:

images:

images: [
  {
    url: 'https://www.example.ie/og-image-01.jpg',
    width: 800,
    height: 600,
    alt: 'Og Image Alt',
  },
],

authors:

authors: [
  'https://www.example.com/authors/@firstnameA-lastnameA',
],

tags:

tags: ['Tag A'],

Supplying multiple of any of the above will not break anything, but only one will be added to the head.

Profile

import { NextSeo } from 'next-seo';

const Page = () => (
  <>
    <NextSeo
      openGraph={{
        title: 'Open Graph Profile Title',
        description: 'Description of open graph profile',
        url: 'https://www.example.com/@firstlast123',
        type: 'profile',
        profile: {
          firstName: 'First',
          lastName: 'Last',
          username: 'firstlast123',
          gender: 'female',
        },
        images: [
          {
            url: 'https://www.test.ie/images/profile.jpg',
            width: 850,
            height: 650,
            alt: 'Profile Photo',
          },
        ],
      }}
    />
    <p>Profile</p>
  </>
);

export default Page;

Note

Multiple images is available from next.js version 7.0.0-canary.0

For versions 6.0.0 - 7.0.0-canary.0 you just need to supply a single item array:

images: [
  {
    url: 'https://www.example.ie/og-image-01.jpg',
    width: 800,
    height: 600,
    alt: 'Og Image Alt',
  },
],

Supplying multiple images will not break anything, but only one will be added to the head.

JSON-LD

Next SEO now has the ability to set JSON-LD a form of structured data. Structured data is a standardised format for providing information about a page and classifying the page content.

Google has excellent content on JSON-LD -> HERE

If using app directory then please ensure to add useAppDir={true} prop and that you are using the component in the page.js

Below you will find a very basic page implementing each of the available JSON-LD types:

Pull request very welcome to add any from the list found on here

JSON-LD Security

Just a quick note on security. To get JSON-LD onto the page it needs to be in a script tag. next-seo achieves this by using a script tag with dangerouslySetInnerHTML.

So if passing anything directly from a URL to one of the components below please ensure you sanitize it first if needed.

View toJson.tsx for implementation detail.

Handling multiple instances

If your page requires multiple instances of a given JSON-LD component, you can specify unique keyOverride properties, and next-seo will handle the rest.

This comes in handy for blog rolls, search results, and overview pages.

Please fully research when you should and shouldn't add multiple instances of JSON-LD.

<ExampleJsonLd keyOverride="my-new-key" />

Article

import { ArticleJsonLd } from 'next-seo';

const Page = () => (
  <>
    <h1>Article JSON-LD</h1>
    <ArticleJsonLd
      useAppDir={false}
      url="https://example.com/article"
      title="Article headline"
      images={[
        'https://example.com/photos/1x1/photo.jpg',
        'https://example.com/photos/4x3/photo.jpg',
        'https://example.com/photos/16x9/photo.jpg',
      ]}
      datePublished="2015-02-05T08:00:00+08:00"
      dateModified="2015-02-05T09:00:00+08:00"
      authorName={[
        {
          name: 'Jane Blogs',
          url: 'https://example.com',
        },
        {
          name: 'Mary Stone',
          url: 'https://example.com',
        },
      ]}
      publisherName="Gary Meehan"
      publisherLogo="https://www.example.com/photos/logo.jpg"
      description="This is a mighty good description of this article."
      isAccessibleForFree={true}
    />
  </>
);

export default Page;

Breadcrumb

import { BreadcrumbJsonLd } from 'next-seo';

const Page = () => (
  <>
    <h1>Breadcrumb JSON-LD</h1>
    <BreadcrumbJsonLd
      itemListElements={[
        {
          position: 1,
          name: 'Books',
          item: 'https://example.com/books',
        },
        {
          position: 2,
          name: 'Authors',
          item: 'https://example.com/books/authors',
        },
        {
          position: 3,
          name: 'Ann Leckie',
          item: 'https://example.com/books/authors/annleckie',
        },
        {
          position: 4,
          name: 'Ancillary Justice',
          item: 'https://example.com/books/authors/ancillaryjustice',
        },
      ]}
    />
  </>
);

export default Page;

Required properties

PropertyInfo
itemListElements
itemListElements.positionThe position of the breadcrumb in the breadcrumb trail. Position 1 signifies the beginning of the trail.
itemListElements.nameThe title of the breadcrumb displayed for the user.
itemListElements.itemThe URL to the webpage that represents the breadcrumb.

Other | useAppDir | This should be set to true if using new app directory. Not required if outside of app directory. |

Blog

import { ArticleJsonLd } from 'next-seo';

const Page = () => (
  <>
    <h1>Blog JSON-LD</h1>
    <ArticleJsonLd
      type="BlogPosting"
      url="https://example.com/blog"
      title="Blog headline"
      images={[
        'https://example.com/photos/1x1/photo.jpg',
        'https://example.com/photos/4x3/photo.jpg',
        'https://example.com/photos/16x9/photo.jpg',
      ]}
      datePublished="2015-02-05T08:00:00+08:00"
      dateModified="2015-02-05T09:00:00+08:00"
      authorName="Jane Blogs"
      description="This is a mighty good description of this blog."
    />
  </>
);

export default Page;

Campground

import { CampgroundJsonLd } from 'next-seo';

const Page = () => (
  <>
    <h1>Campground JSON-LD</h1>
    <CampgroundJsonLd
      id="https://www.example.com/campground/rip-van-winkle-campground"
      name="Rip Van Winkle Campgrounds"
      url="https://www.example.com/campground"
      telephone="+18452468114"
      images={['https://example.com/photos/1x1/photo.jpg']}
      address={{
        streetAddress: '149 Blue Mountain Rd',
        addressLocality: 'Saugerties',
        addressRegion: 'NY',
        postalCode: '12477',
        addressCountry: 'US',
      }}
      description="Description about Rip Van Winkle Campgrounds"
      geo={{
        latitude: '42.092599',
        longitude: '-74.018580',
      }}
      openingHours={[
        {
          opens: '09:00',
          closes: '17:00',
          dayOfWeek: [
            'Monday',
            'Tuesday',
            'Wednesday',
            'Thursday',
            'Friday',
            'Saturday',
            'Sunday',
          ],
          validFrom: '2019-12-23',
          validThrough: '2020-04-02',
        },
      ]}
      petsAllowed
      rating={{
        ratingValue: '5',
        ratingCount: '18',
      }}
      amenityFeature={{
        name: 'Showers',
        value: true,
      }}
      priceRange="$$"
    />
  </>
);

export default Page;

Required properties

PropertyInfo
@idGlobally unique ID of the specific campground in the form of a URL.
addressAddress of the specific campground location
address.addressCountryThe 2-letter ISO 3166-1 alpha-2 country code
address.addressLocalityCity
address.addressRegionState or province, if applicable.
address.postalCodePostal or zip code.
address.streetAddressStreet number, street name, and unit number.
nameCampground name.
descriptionCampground description.

Supported properties

PropertyInfo
geoGeographic coordinates of the campground.
geo.latitudeThe latitude of the campground location
geo.longitudeThe longitude of the campground location
imagesAn image or images of the campground. Required for valid markup depending on the type
telephoneA campground phone number meant to be the primary contact method for customers.
urlThe fully-qualified URL of the specific campground.
openingHoursOpening hour specification of the campground. You can provide this as a single object, or an array of objects with the properties below.
openingHours.opensThe opening hour of the place or service on the given day(s) of the week.
openingHours.closesThe closing hour of the place or service on the given day(s) of the week.
openingHours.dayOfWeekThe day of the week for which these opening hours are valid. Can be a string or array of strings. Refer to DayOfWeek
openingHours.validFromThe date when the item becomes valid.
openingHours.validThroughThe date after when the item is not valid.
isAccessibleForFreeWhether or not the campground is accessible for free.
petsAllowedWhether or not the campgroud allows pets.
amenityFeatureAn amenity feature (e.g. a characteristic or service) of the campground.
amenityFeature.nameThe name of the amenity.
amenityFeature.valueThe value of the amenity.
priceRangeThe price range of the campground, for example $$$.
ratingThe average rating of the campground based on multiple ratings or reviews.
rating.ratingValueThe rating for the content.
rating.ratingCountThe count of total number of ratings.

Other | useAppDir | This should be set to true if using new app directory. Not required if outside of app directory. |

Recipe

import { RecipeJsonLd } from 'next-seo';

const Page = () => (
  <>
    <h1>Recipe JSON-LD</h1>
    <RecipeJsonLd
      name="Party Coffee Cake"
      description="This coffee cake is awesome and perfect for parties."
      datePublished="2018-03-10"
      authorName={['Jane Blogs', 'Mary Stone']}
      prepTime="PT20M"
      cookTime="PT30M"
      totalTime="PT50M"
      keywords="cake for a party, coffee"
      yields="10"
      category="Dessert"
      cuisine="American"
      calories={270}
      images={[
        'https://example.com/photos/1x1/photo.jpg',
        'https://example.com/photos/4x3/photo.jpg',
        'https://example.com/photos/16x9/photo.jpg',
      ]}
      ingredients={[
        '2 cups of flour',
        '3/4 cup white sugar',
        '2 teaspoons baking powder',
        '1/2 teaspoon salt',
        '1/2 cup butter',
        '2 eggs',
        '3/4 cup milk',
      ]}
      instructions={[
        {
          name: 'Preheat',
          text: 'Preheat the oven to 350 degrees F. Grease and flour a 9x9 inch pan.',
          url: 'https://example.com/party-coffee-cake#step1',
          image: 'https://example.com/photos/party-coffee-cake/step1.jpg',
        },
      ]}
      aggregateRating={{
        ratingValue: '5',
        ratingCount: '18',
      }}
      video={{
        name: 'How to make a Party Coffee Cake',
        description: 'This is how you make a Party Coffee Cake.',
        contentUrl: 'http://www.example.com/video123.mp4',
        embedUrl: 'http://www.example.com/videoplayer?video=123',
        uploadDate: '2018-02-05T08:00:00+08:00',
        duration: 'PT1M33S',
        thumbnailUrls: [
          'https://example.com/photos/1x1/photo.jpg',
          'https://example.com/photos/4x3/photo.jpg',
          'https://example.com/photos/16x9/photo.jpg',
        ],
        expires: '2019-02-05T08:00:00+08:00',
        hasPart: {
          '@type': 'Clip',
          name: 'Preheat oven',
          startOffset: 30,
          url: 'http://www.example.com/example?t=30',
        },
        watchCount: 2347,
        publication: {
          '@type': 'BroadcastEvent',
          isLiveBroadcast: true,
          startDate: '2020-10-24T14:00:00+00:00',
          endDate: '2020-10-24T14:37:14+00:00',
        },
        regionsAllowed: ['IT', 'NL'],
      }}
    />
  </>
);

export default Page;

Required properties

PropertyInfo
nameThe name of the recipe
descriptionA description of the recipe
authorNameThe name of the recipe author. Can be a string or array of strings.
ingredientsA list of ingredient strings
instructions-
instructions.nameThe name of the instruction step.
instructions.textThe directions of the instruction step.

Other | useAppDir | This should be set to true if using new app directory. Not required if outside of app directory. |

Sitelinks Search Box

import { SiteLinksSearchBoxJsonLd } from 'next-seo';

const Page = () => (
  <>
    <h1>Sitelinks Search Box JSON-LD</h1>
    <SiteLinksSearchBoxJsonLd
      url="https://www.example.com"
      potentialActions={[
        {
          target: 'https://query.example.com/search?q',
          queryInput: 'search_term_string',
        },
        {
          target: 'android-app://com.example/https/query.example.com/search/?q',
          queryInput: 'search_term_string',
        },
      ]}
    />
  </>
);

export default Page;

Required properties

PropertyInfo
urlURL of the website associated with the sitelinks searchbox
potentialActionsArray of one or two SearchAction objects. Describes the URI to send the query to, and the syntax of the request that is sent
potentialActions.targetFor websites, the URL of the handler that should receive and handle the search query; for apps, the URI of the intent handler for your search engine that should handle queries
potentialActions.queryInputPlaceholder used in target, gets substituted for user given query

Other | useAppDir | This should be set to true if using new app directory. Not required if outside of app directory. |

Read the documentation

Course

import { CourseJsonLd } from 'next-seo';

const Page = () => (
  <>
    <h1>Course JSON-LD</h1>
    <CourseJsonLd
      courseName="Course Name"
      description="Introductory CS course laying out the basics."
      provider={{
        name: 'Course Provider',
        url: 'https//www.example.com/provider',
      }}
    />
  </>
);

export default Page;

Required properties

PropertyInfo
courseNameThe title of the course.
descriptionA description of the course. Display limit of 60 characters.
provider.nameThe course provider name.
provider.urlThe course provider name url.

Recommended properties

PropertyInfo
providerUrlThe url to the course provider.

Other | useAppDir | This should be set to true if using new app directory. Not required if outside of app directory. |

Dataset

import { DatasetJsonLd } from 'next-seo';

const Page = () => (
  <>
    <h1>Dataset JSON-LD</h1>
    <DatasetJsonLd
      description="The description needs to be at least 50 characters long"
      name="name of the dataset"
      license="https//www.example.com"
    />
  </>
);

export default Page;

Required properties

PropertyInfo
descriptionA short summary describing a dataset. Needs to be between 50 and 5000 characters.
nameA license under which the dataset is distributed.

Recommended properties

PropertyInfo
licenseThe url to the course provider.

Other | useAppDir | This should be set to true if using new app directory. Not required if outside of app directory. |

Corporate Contact

import { CorporateContactJsonLd } from 'next-seo';

const Page = () => (
  <>
    <h1>Corporate Contact JSON-LD</h1>
    <CorporateContactJsonLd
      url="http://www.your-company-site.com"
      logo="http://www.example.com/logo.png"
      contactPoint={[
        {
          telephone: '+1-401-555-1212',
          contactType: 'customer service',
          email: 'customerservice@email.com',
          areaServed: 'US',
          availableLanguage: ['English', 'Spanish', 'French'],
        },
        {
          telephone: '+1-877-746-0909',
          contactType: 'customer service',
          email: 'servicecustomer@email.com',
          contactOption: 'TollFree',
          availableLanguage: 'English',
        },
        {
          telephone: '+1-877-453-1304',
          contactType: 'technical support',
          contactOption: 'TollFree',
          areaServed: ['US', 'CA'],
          availableLanguage: ['English', 'French'],
        },
      ]}
    />
  </>
);

export default Page;

Required properties

PropertyInfo
urlUrl to the home page of the company's official site.
contactPoint
contactPoint.telephoneAn internationalized version of the phone number, starting with the "+" symbol and country code
contactPoint.contactTypeDescription of the purpose of the phone number i.e. Technical Support.

Recommended ContactPoint properties

PropertyInfo
contactPoint.areaServedString or Array of geographical regions served by the business. Example "US" or ["US", "CA", "MX"]
contactPoint.availableLanguageDetails about the language spoken. Example "English" or ["English", "French"]
contactPoint.emailEmail asscosiated with the business`
gecontactPointo.contactOptionDetails about the phone number. Example "TollFree"

Other | useAppDir | This should be set to true if using new app directory. Not required if outside of app directory. |

FAQ Page

import { FAQPageJsonLd } from 'next-seo';

const Page = () => (
  <>
    <h1>FAQ Page JSON-LD</h1>
    <FAQPageJsonLd
      mainEntity={[
        {
          questionName: 'How long is the delivery time?',
          acceptedAnswerText: '3-5 business days.',
        },
        {
          questionName: 'Where can I find information about product recalls?',
          acceptedAnswerText: 'Read more on under information.',
        },
      ]}
    />
  </>
);

export default Page;

Required properties

PropertyInfo
mainEntity
mainEntity.questionNameThe full text of the question. For example, "How long is the delivery time?".
mainEntity.acceptedAnswerTextThe full answer to the question.

Other | useAppDir | This should be set to true if using new app directory. Not required if outside of app directory. |

How-to

import { HowToJsonLd } from 'next-seo';

const Page = () => (
  <>
    <h1>How-to JSON-LD</h1>
    <HowToJsonLd
      name="How to tile a kitchen backsplash"
      image="https://example.com/photos/1x1/photo.jpg"
      estimatedCost={{ currency: 'USD', value: '100' }}
      supply={['tiles', 'thin-set', 'mortar', 'tile grout', 'grout sealer']}
      tool={['notched trowel', 'bucket', 'large sponge']}
      step={[
        {
          url: 'https://example.com/kitchen#step1',
          name: 'Prepare the surfaces',
          itemListElement: [
            {
              type: 'HowToTip',
              text: 'Turn off the power to the kitchen and then remove everything that is on the wall, such as outlet covers, switchplates, and any other item in the area that is to be tiled.',
            },
            {
              type: 'HowToDirection',
              text: 'Then clean the surface thoroughly to remove any grease or other debris and tape off the area.',
            },
          ],
          image: 'https://example.com/photos/1x1/photo-step1.jpg',
        },
      ]}
      totalTime="P2D"
    />
  </>
);

export default Page;

Required properties

PropertyInfo
@neuvernetzung/cmsresource-centersous-vide-diariesaudio-tour-hamada@ranapp/templateaidexa-open-dspylot-frameworktodoist-landing-pages@infinitebrahmanuniverse/nolb-next-s@spely-co/nextjscyrilo-portfoliojob-web-app@everything-registry/sub-chunk-2268@kitql/websitedsch-donedeal-frontendnoot-cosmeticslinkinthebioliendanslabioguild-docsnext-ts-chakra-templatenextwromo-storelumen-cms-corelumen-cms-baseluganonextra-theme-chocolatenextra-theme-docs-bestnextra-theme-docs-best1nextra-theme-docs-beta.1nextra-theme-docs-mdxcomponentsnextra-theme-docs-osonextra-theme-infpnomadr-ui-nextengrafiadroppii-b2bfrietor-nextra-themegeru-components@deus-labs/tools-componentsnuudel-coreproject-nextprimeobjects-ui-web-applicationsearch-buttonsection-blog-themesection-theme-blog@gem-sdk/pages@eteg/nextra-theme-docs@gravis-os/landing@faststore/core@gan-dev/roots@infinum/nextra-theme-docs@icebreakers/nextra-theme-docsvoluptatemsed@minou/core@kuda-terbang/nextjs-client-template@lightdotso/common@lightdotso/core@newhighsco/press-start@neato/guider@m3cms/faststore-core@m3cms/seo@digital-garden-builder/clientculinary-portal-preview-componentsusanoo-cmstailwind-nextjs-typescript-starter-blogdapp-nextsridharshunkakinoki.com@lightsohq/home@llllvvuu/nextra-theme-docs@nullfox/nextjs-blog@speakeasy-sdks/nextra-theme-docs@therealcodekraft/kinow-frontend@visi/web-client@visiture/pwa-fe@visiture/shopify@visulima/nextra-theme-docs@sentrei/ui@sentrei/web@ntrongd/commerce-server@ntrongd/commerce-web@poap-xyz/frames@react-test-storefront/create-medusa-template@react-test-storefront/create-medusa-template2@react-test-storefront/medusa-theme-starter@strata-foundation/chat-ui@strata-foundation/marketplace-ui@strata-foundation/site@sridharbashaveni/servicegpr@startertemp/nextjs-hardhat@startertemp/nextjs-hardhat-ts@studio-freight/compono@secrecy/front-utils@types/next-seo@websub_npm/wscl@yearn-finance/web-lib@whhjdi/nextra-theme-docs@zalastax/nolb-next-s@0xforkitall/ui-kit-nextjs@app-box/web@artcoded/next-common@artcoded/next-storefront
6.5.0

1 month ago

6.2.0

5 months ago

6.3.0

5 months ago

6.4.0

5 months ago

6.1.0

9 months ago

6.0.0

12 months ago

5.15.0

1 year ago

5.11.1

1 year ago

5.11.0

1 year ago

5.8.0

1 year ago

5.12.0

1 year ago

5.9.0

1 year ago

5.13.0

1 year ago

5.6.0

1 year ago

5.14.1

1 year ago

5.14.0

1 year ago

5.10.0

1 year ago

5.7.0

1 year ago

5.5.0

2 years ago

5.3.0

2 years ago

5.4.0

2 years ago

5.2.0

2 years ago

5.1.0

2 years ago

5.0.0

2 years ago

4.29.0

2 years ago

4.28.1

3 years ago

4.28.0

3 years ago

4.27.0

3 years ago

4.26.0

3 years ago

4.25.0

3 years ago

4.25.1

3 years ago

4.24.0

3 years ago

4.23.0

3 years ago

4.21.0

3 years ago

4.22.0

3 years ago

4.20.0

3 years ago

4.19.0

3 years ago

4.18.0

3 years ago

4.17.0

3 years ago

4.16.0

3 years ago

4.15.1

3 years ago

4.15.0

3 years ago

4.14.1

3 years ago

4.14.0

3 years ago

4.12.0

3 years ago

4.13.0

3 years ago

4.11.0

3 years ago

4.10.1

3 years ago

4.10.0

4 years ago

4.9.0

4 years ago

4.8.0

4 years ago

4.7.3

4 years ago

4.7.2

4 years ago

4.7.1

4 years ago

4.7.0-beta.1

4 years ago

4.7.0

4 years ago

4.7.0-beta.0

4 years ago

4.6.0

4 years ago

4.5.0

4 years ago

4.4.0

4 years ago

4.3.0

4 years ago

4.2.0

4 years ago

4.1.0

4 years ago

4.0.0

4 years ago

3.4.0

4 years ago

3.3.0

4 years ago

3.2.0

4 years ago

3.1.0

4 years ago

3.0.0

4 years ago

2.2.1

4 years ago

2.2.0

4 years ago

2.1.2

4 years ago

2.1.1

4 years ago

2.1.0

5 years ago

2.0.0

5 years ago

1.12.0

5 years ago

2.0.0-alpha.1

5 years ago

2.0.0-alpha.0

5 years ago

1.11.2

5 years ago

1.11.1

5 years ago

1.11.0

5 years ago

1.10.1

5 years ago

1.10.0

5 years ago

1.9.0

5 years ago

1.8.0

5 years ago

1.7.0

5 years ago

1.6.0

5 years ago

1.5.0

5 years ago

1.4.0

5 years ago

1.3.0

5 years ago

1.2.0

6 years ago

1.1.2

6 years ago

1.1.1

6 years ago

1.1.0

6 years ago

1.0.2

6 years ago

1.0.1

6 years ago

1.0.0

6 years ago

0.0.7

6 years ago

0.0.6

6 years ago

0.0.5

6 years ago

0.0.4

6 years ago

0.0.3

6 years ago

0.0.2

6 years ago

0.0.1

6 years ago