Skip to main content
seofields
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

OptionTypeDefaultDescription
seoPreviewboolean | objecttrueEnable/disable live SEO preview, or pass an object with a custom prefix, titleSuffix (string | function), titleSuffixQuery (GROQ), and titleSuffixInheritColor. Configured title suffixes are also included in Meta Title validation feedback.
baseUrlstringhttps://www.example.comBase URL prepended to slugs in the SEO preview.
apiVersionstring'2024-01-01'Sanity Content Lake API version used by the SEO preview's GROQ fetches and the SEO Health Dashboard. Centralizes versioning so you don't have to set it per-feature.
fieldOverridesPartial<Record<FieldKey, { title?, description? }>>{}Customize field labels and helper text for any SEO field.
fieldVisibilityRecord<string, { hiddenFields? }>{}Hide specific SEO fields for a given document type.
defaultHiddenFieldsValidHiddenFieldKeys[][]Hide SEO fields globally across all document types.
fieldGroupsSeoFieldGroup[]undefinedOrganize 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.
healthDashboardboolean | objecttrueEnable/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 + suffix branding
      seoPreview: {
        prefix: (doc) => `/${doc.slug?.current || 'page'}`,
        // Static suffix appended to the SERP preview title — plugin adds " | " automatically
        // and includes it in Meta Title validation length checks.
        titleSuffix: 'Acme Inc',
        // Match parent title color (blue, weight 500) instead of muted gray
        titleSuffixInheritColor: true,
      },

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

      // Sanity API version — used by SEO preview GROQ + Health Dashboard
      apiVersion: '2024-01-01',

      // 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: 'Editorial Keywords',
          description: 'Internal keywords for editorial workflows and content audits',
        },
      },

      // 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}`
  }
})

// Static brand suffix appended to the SERP title preview — provide only the text, plugin adds " | "
seofields({
  seoPreview: {
    titleSuffix: 'Acme Inc',
    titleSuffixInheritColor: true, // match parent title color
  }
})

// Function-based titleSuffix — derive from document data
seofields({
  seoPreview: {
    titleSuffix: (doc) => doc?.brandName ?? '',
  }
})

// Dynamic titleSuffix from a GROQ query — wins over titleSuffix
seofields({
  seoPreview: {
    titleSuffixQuery: `*[_id == "siteSettings"][0].titleSuffix`,
    titleSuffixInheritColor: true,
  }
})

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.

Last updated: May 27, 2026. Tested with: Sanity Studio v3, v4, and v5.

Was this page helpful?