Learn how to integrate the Payload SEO plugin with your Next.js app—covering everything from installation and basic configuration to adding custom SEO fields for dynamic, optimized meta data.

In this guide, I’m walking you through how to use the Payload SEO Plugin. We’ll cover everything from installation and basic configuration to adding custom SEO fields. If you’re looking to auto‑generate SEO-friendly titles, descriptions, URLs, and more directly from your CMS fields, then you’re in the right place.

You’ll learn how to:

Install and configure the SEO plugin in Payload
Auto‑generate meta titles, descriptions, and URLs
Add custom fields like canonical URLs
Structure your SEO data within your Payload collections

About the Payload SEO plugin

In this video, we kick things off by introducing Payload's free SEO plugin. Once you add the plugin to a collection or global settings, a meta field group is automatically injected into your collection or global. By default, this group includes a title, description, and image. You can also extend the plugin to include any extra SEO fields you might need—say, a canonical URL or even schema markup.

I personally like generating my schema markup on the front end, but defining those fields directly in the plugin is a breeze if that’s your style. The idea is to reduce duplication of work while ensuring your SEO data stays in sync.

Beyond extending the fields in the plugin, you can define functions that automatically generate titles, descriptions, and more—making it even easier for you or your editors to populate your website's SEO information into your website without duplicating effort.

Installing the SEO plugin

To get started, all you have to do is install the plugin. Open your terminal and run: pnpm add @payloadcms/plugin-seo

Make sure the plugin’s version matches your other Payload dependencies. In my setup, I adjusted the version if needed in the package.json and then ran: pnpm i

Once the plugin is installed, import it at the top of your Payload config file:

1import {seoPlugin} from 'payloadcms/plugin-seo';

Then add it to your plugins array—or create one if you haven't already—in the Payload configuration.

Configuring the SEO Plugin

After installation, it’s time to tweak the base configurations. Open your Payload config file and locate the plugins array. You should add an entry for the SEO plugin.

For example:

1plugins: [
seoPlugin({
  collections: ['posts'],
  uploadsCollection: 'media',
  generateTitle: {doc} => doc.title,
  generateDescription: {doc} => doc.plainText,
  generateURL: ({doc, collectionSlug}) => `https://example.com/${collectionSlug}/${doc?.slug}`,
}),
9],

This configuration tells Payload to add SEO meta fields (like title, description, and image) to your specified collections—in this case, for the posts collection. It also sets up functions to auto‑generate these fields based on your document content.

Make sure to run:payload generate: importmap and run pnpm dev to spin up our localhost.

Reviewing the Changes to the Admin UI

After logging into your admin panel (e.g., via localhost:3000/admin), navigate to your blog posts, and you’ll now see the SEO fields added automatically at the bottom of the document. You can auto‑generate values for the title and description right from there

Upon publishing a test post using your new fields, you should be able to click the API tab and see the meta fields within the JSON output.

If you want a different arrangement—say, putting these fields on a dedicated SEO tab rather than at the bottom—you can adjust the configuration by adding the tabbedUI: true option.

Using tabbed UI for a cleaner setup

1plugins: [
seoPlugin({
  collections: ['posts'],
  uploadsCollection: 'media',
  generateTitle: {doc} => doc.title,
  generateDescription: {doc} => doc.plainText,
  generateURL: ({doc, collectionSlug}) => `https://example.com/${collectionSlug}/${doc?.slug}`,
  tabbedUI: true, // Allows us to have a tabbed UI for a cleaner interface
}),
10],

Once saved, refresh your document. You’ll notice a new SEO tab at the top, keeping your main content and SEO data cleanly separated.

These functions accept various arguments—like the document id, locale, Collection or Global config, and even the Payload request object—letting you query additional documents or perform other changes as needed. Additionally, by incorporating your own image field in your collection, you can use generateImage to quickly populate a featured meta image with a single click.

Customizing and extending SEO fields

One great thing about the SEO plugin is its flexibility. You can add custom fields if you need more control over your SEO metadata. For example, you might want to include a canonical URL. To do that, extend the plugin config by specifying additional fields:

1seoPlugin({
...,
tabbedUI: true,
fields: (defaultFields) => [
  ...defaultFields,
  {
    name: 'canonicalURL',
    type: 'text',
    label: 'Canonical URL',
  },
],
12}),

This custom field now appears along with the default SEO fields in your admin UI.

Using SEO fields directly in a Collection

For a more tailored setup, you can remove the SEO plugin’s default field grouping (so leave all "generate" functions in place) and integrate the fields directly into your Collection’s schema. For instance, in your posts collection config, you could wrap everything inside a tab field.

1import {MetaDescriptionField, MetaImageField, MetaTitleField, OverviewField, PreviewField} from '@payloadcms/plugin-seo/fields' 
2// To add the SEO fields into the new 'SEO' tab (row 60), 
3// we need to import them the Payload SEO plugin
4
..
6
 fields: [
  {
    type: 'tabs',
    tabs: [ 
      {
        label: 'Content',
        fields: [ // In this tab is where we are 
        // wrapping everything (example below)
          {
            type: 'blocks',
            admin: {
              initCollapsed: true,
              isSortable: false,
            },
            blocks: [
              ContentWithMedia, TableOfContents,
            ],
            name: 'blockTest',
            label: false,
            minRows: 1,
            maxRows: 20,
          },
          {
            name: 'title',
            type: 'text',
          },
          {
            name: 'slug',
            type: 'text',
          },
          {
            name: 'content',
            type: 'richText',
            editor: lexicalEditor({
              features: ({ defaultFeatures }) => [
                ...defaultFeatures,
                BlocksFeature({
                  blocks: [ContentWithMedia, TableOfContents],
                }),
                FixedToolbarFeature(),
              ],
            }),
          },
          {
            name: 'plaintext',
            type: 'textarea',
          },
          { name: 'number', type: 'number' },
          {
            name: 'usersArray',
            type: 'array',
            fields: [{ name: 'users', type: 'relationship', relationTo: 'users' }],
          },
        ],
      },
      {
        label: 'SEO', 
        name: 'meta',
        fields: [
          MetaTitleField({
            hasGenerateFn: true,
            overrides: {
              label: 'Title'
            }
          }),
          MetaDescriptionField({
            hasGenerateFn: true,
          }),
          MetaImageField({
            relationTo: 'media'
          }),
          {
            type: 'text',
            name: 'canonicalUrl',
            label: 'Canonical URL',
            hooks: { // More on this below
              beforeChange: [
                async ({data, value}) => !value ? `https://example.com/posts/${data?.slug}` : value
              ]
            }
          },
          PreviewField({
            hasGenerateFn: true,
            titlePath: 'meta.title',
            descriptionPath: 'meta.description',
          }),
          OverviewField({
            titlePath: 'meta.title',
            descriptionPath: 'meta.description',
            imagePath: 'meta.image',
          })
        ]
      },
    ],
  },
],

Leveraging hooks for default values

Sometimes you want the system to take care of defaults. For example, you could use a beforeChange hook to set a default canonical URL if none is provided. In your custom field definition, you can add a hook like so:

1MetaImageField({
            relationTo: 'media'
          }),
          {
            type: 'text',
            name: 'canonicalUrl',
            label: 'Canonical URL',
            hooks: { 
              beforeChange: [
                async ({data, value}) => !value ? `https://example.com/posts/${data?.slug}` : value
              ]
            }
          },

By using this hook, any changes won’t overwrite my custom canonical URL—so after saving and publishing, I can see that the canonical URL is correctly populated.

Final thoughts and what’s next

The configuration options for the SEO plugin are endlessly flexible and extensible. Today we covered the basics—installing the plugin, configuring your meta fields, using a tabbed UI for cleaner organization, and even adding custom fields. There’s a ton more you can do, such as incorporating schema markup or (coming soon) dynamic variable injection down the road.

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.

How to install and configure the Payload SEO plugin