docs

Configuration

Customize every aspect of the plugin — from field labels to preview behavior.

Basic Configuration

The plugin works with zero configuration:

sanity.config.ts

import seofields from 'sanity-plugin-seofields'

export default defineConfig({
  plugins: [
    seofields(),  // All defaults — preview, dashboard, all fields
  ],
})

Configuration Options

Option	Type	Default	Description
`seoPreview`	boolean \| object	true	Enable/disable live SEO preview, or pass an object with a custom prefix function.
`baseUrl`	string	https://www.example.com	Base URL prepended to slugs in the SEO preview.
`fieldOverrides`	Partial<Record<FieldKey, { title?, description? }>>	{}	Customize field labels and helper text for any SEO field.
`fieldVisibility`	Record<string, { hiddenFields? }>	{}	Hide specific SEO fields for a given document type.
`defaultHiddenFields`	ValidHiddenFieldKeys[]	[]	Hide SEO fields globally across all document types.
`fieldGroups`	SeoFieldGroup[]	undefined	Organize SEO fields into tabbed groups (Sanity groups). Each group defines a tab with a name, title, and list of fields. See the Field Groups docs for details.
`healthDashboard`	boolean \| object	true	Enable/disable the SEO Health Dashboard, or pass an object to fully configure it (tool title, queries, display columns, badges, etc.). See the Dashboard → Configuration docs for all sub-options.

Advanced Configuration

sanity.config.ts

import seofields, { SeoFieldsPluginConfig } from 'sanity-plugin-seofields'

export default defineConfig({
  plugins: [
    seofields({
      // Live SERP preview with custom URL prefix
      seoPreview: {
        prefix: (doc) => `/${doc.slug?.current || 'page'}`
      },

      // Base URL for preview
      baseUrl: 'https://www.example.com',

      // Customize field labels and descriptions
      fieldOverrides: {
        title: {
          title: 'Page Title',
          description: 'The main title that appears in search results',
        },
        description: {
          title: 'Meta Description',
          description: 'A brief summary for search engines',
        },
        canonicalUrl: {
          title: 'Canonical URL',
          description: 'Preferred URL to avoid duplicate content',
        },
        metaImage: {
          title: 'Social Media Image',
          description: 'Image used when sharing on social platforms',
        },
        keywords: {
          title: 'SEO Keywords',
          description: 'Keywords describing the page content',
        },
      },

      // Hide fields on specific document types
      fieldVisibility: {
        page: {
          hiddenFields: ['openGraphSiteName', 'twitterSite'],
        },
        post: {
          hiddenFields: ['openGraphSiteName', 'twitterSite'],
        },
      },

      // Or hide fields globally
      defaultHiddenFields: ['openGraphSiteName', 'twitterSite'],

      // Organize fields into tabbed groups
      fieldGroups: [
        { name: 'meta', title: 'Meta', default: true,
          fields: ['title', 'description', 'metaImage', 'keywords', 'canonicalUrl', 'metaAttributes', 'robots'] },
        { name: 'openGraph', title: 'Open Graph', fields: ['openGraph'] },
        { name: 'twitter', title: 'Twitter Card', fields: ['twitter'] },
      ],

      // SEO Health Dashboard — set false to disable, or pass an object to configure
      healthDashboard: {
        licenseKey: 'SEOF-XXXX-XXXX-XXXX',
        tool: { title: 'SEO Audit', name: 'seo-audit' },
        showTypeColumn: true,
        showDocumentId: false,
        query: { types: ['post', 'page'] },
      },
      // healthDashboard: false, // disable entirely
    } satisfies SeoFieldsPluginConfig),
  ],
})

fieldGroups

The fieldGroups option lets you organize SEO fields into tabbed groups inside the seoFields object. This uses Sanity's native groups feature to render tabs in Studio.

📑View full fieldGroups option reference

healthDashboard

The healthDashboard key accepts true (default — all defaults), false (disabled), or a configuration object with options for the tool tab, content text, query filtering, column visibility, type labels, custom badges, and more.

📊View full healthDashboard option reference

SEO Preview Options

The seoPreview option controls the live SERP preview shown alongside SEO fields:

Preview options

// Disable preview entirely
seofields({ seoPreview: false })

// Enable with default behavior
seofields({ seoPreview: true })

// Custom URL prefix using document data
seofields({
  seoPreview: {
    prefix: (doc) => `/blog/${doc.slug?.current}`
  }
})

Available Field Keys

These keys can be used in both fieldOverrides and fieldVisibility:

title

description

canonicalUrl

metaImage

keywords

metaAttributes

robots

openGraphUrl

openGraphTitle

openGraphDescription

openGraphSiteName

openGraphType

openGraphImage

twitterCard

twitterSite

twitterCreator

twitterTitle

twitterDescription

twitterImage

Tip: Hiding openGraphImage or twitterImage also hides their URL and type variants to keep the editor experience consistent.

Was this page helpful?