Configuration
Customize every aspect of the plugin — from field labels to preview behavior.
Basic Configuration
The plugin works with zero configuration:
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, titleSuffix (string | function), titleSuffixQuery (GROQ), and titleSuffixInheritColor. Configured title suffixes are also included in Meta Title validation feedback. |
baseUrl | string | https://www.example.com | Base URL prepended to slugs in the SEO preview. |
apiVersion | string | '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. |
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
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.
fieldGroups option referencehealthDashboard
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.
healthDashboard option referenceSEO Preview Options
The seoPreview option controls the live SERP preview shown alongside SEO fields:
// 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:
titledescriptioncanonicalUrlmetaImagekeywordsmetaAttributesrobotsopenGraphUrlopenGraphTitleopenGraphDescriptionopenGraphSiteNameopenGraphTypeopenGraphImagetwitterCardtwitterSitetwitterCreatortwitterTitletwitterDescriptiontwitterImageTip: 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?