Configuration Options

Without a valid licenseKey the SEO Health tab will not render any data. Keys follow the SEOF-XXXX-XXXX-XXXX format and are tied to your Sanity project ID.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
  },
})

The default is stable and works for all current Sanity projects. Only change this if you need a specific API version for compatibility reasons.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    apiVersion: '2024-01-01',
  },
})

The text that appears as the tool's tab name in the Sanity Studio sidebar. The heading inside the dashboard page is controlled separately via content.title.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    tool: { title: 'SEO Audit' },
  },
})

The internal identifier for the tool. Only change this if you register multiple instances or have a naming conflict with another Studio tool.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    tool: { name: 'my-seo-tool' },
  },
})

Rendered next to the title inside the dashboard page. Any single emoji works.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    content: { icon: '🔍' },
  },
})

Replaces the default page heading inside the dashboard. The Studio nav tab label is controlled separately via tool.title.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    content: { title: 'Content SEO Audit' },
  },
})

Adds a short description below the dashboard heading. Useful for giving editors context about what the dashboard shows.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    content: { description: 'Track SEO quality across all published blog posts.' },
  },
})

Replaces the default spinner message displayed while the dashboard checks your license key against the server. Useful for matching your team's language or branding.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    content: { loadingLicense: 'Checking your plan…' },
  },
})

Replaces the default spinner message while the GROQ query is in flight. Helpful when fetching a large content set and you want to set editor expectations.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    content: { loadingDocuments: 'Fetching your content, hang tight…' },
  },
})

Displayed in place of the table when no documents match the current query, search, or filter. You can tailor this message to match your content model — e.g. tell editors which document types are expected to have SEO fields.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    content: { noDocuments: 'No pages with SEO fields yet — try publishing one first.' },
  },
})

Defaults to true. Set to false to hide the _type column — useful when all your documents are the same type.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    showTypeColumn: false,
  },
})

Defaults to true. Exposes the raw document ID in the table. Set to false for a cleaner editor UI.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    showDocumentId: false,
  },
})

Restricts the built-in query to only the listed document types. By default (nothing set) all types with a non-null seo field are included. Ignored entirely when query.groq is also set — see the precedence callout above.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    query: { types: ['post', 'page', 'product'] },
  },
})

When true (the default), documents where seo is null or missing are excluded from the results. Set to false to include all documents of the queried types even if they have no seo field. This option is only meaningful when query.types is set — it has no effect when query.groq is used, since your custom query controls filtering entirely.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    query: { requireSeo: false },
  },
})

Highest priority — when set, query.types and query.requireSeo are both ignored entirely. The dashboard runs your GROQ string verbatim. Use this when you need full control over filtering (e.g. exclude drafts, filter by a nested field, or join across document types).

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    query: {
      groq: `*[_type == "post" && defined(title) && !(_id in path("drafts.**"))] {
        _id, _type, title, seo, _updatedAt
      }`,
    },
  },
})

Used in both the Type column and the Type filter dropdown. Any _type without an entry falls back to the raw _type string. Useful when your document type names are technical (e.g. productDrug) and you want editors to see friendly names (e.g. Products).

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    typeDisplayLabels: {
      productDrug: 'Products',
      singleCondition: 'Condition',
      landingPage: 'Landing Page',
    },
  },
})

badge (default) renders each type as a coloured pill. Badge colours are assigned dynamically: a deterministic hash of the _type string picks a colour from a 16-colour palette, so every type — including custom ones — automatically gets a distinct, consistent colour with no configuration needed. text renders it as plain inline text — useful for dense layouts or when badge colours feel distracting.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    typeColumnMode: 'text',
  },
})

By default the dashboard reads the title field on every document. If some of your document types store the display name in a different field (e.g. name, label, heading), set titleField to that field name. Pass a string to use the same field across all types, or a Record<string, string> to specify a different field per type. Unmapped types always fall back to title.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    // Same field for all types
    titleField: 'name',

    // — or — per-type mapping
    titleField: {
      post: 'title',
      product: 'name',
      category: 'label',
    },
  },
})

When true, the dashboard bypasses license validation and skips all Sanity queries. Instead it renders a set of sample documents covering the full score range (excellent → missing). An amber 'Preview Mode' badge is shown in the dashboard header so editors know the data is not real. Useful for documentation screenshots, showcasing the dashboard to stakeholders, or testing the UI before your content model is in place.

seofields({
  healthDashboard: {
    previewMode: true,
  },
})

When you have multiple structure tools registered in your Sanity Studio, the generic intent resolver always picks the first one. Set structureTool to the name of the tool that contains your monitored documents (e.g. 'common') and clicking a document title will navigate directly to /{basePath}/{structureTool}/intent/edit/id=…;type=…/ instead.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    structureTool: 'common', // the `name` of your structure tool
  },
})

When true (the default), both a 'Export CSV' and 'Export JSON' button appear in the controls bar. The export always reflects the current search query, status filter, type filter, and sort order — exactly the rows visible on screen. Set to false to hide all export controls. Pass an object to enable only specific formats.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',

    // Disable export entirely
    export: false,

    // — or — enable only CSV
    export: { formats: ['csv'] },

    // — or — enable only JSON
    export: { formats: ['json'] },
  },
})

When false (default), the dashboard renders the familiar 6-card grid showing Total, Avg Score, Excellent, Good, Fair, and Poor/Missing counts. When true, that grid is hidden and a compact pill row is shown inside the header instead — for example: '📋 12 · 🟢 Excellent: 4 · 🟡 Good: 3 · 🟠 Fair: 2 · 🔴 Poor/Missing: 3 · 📊 Avg: 65% · 🗂️ Types: 2'. Useful in dense dashboards or when vertical space is at a premium.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    compactStats: true,
  },
})

The function receives the full document object (including any custom fields your schema defines) and should return a badge descriptor or undefined to render nothing. bgColor and textColor accept any valid CSS colour value. Tip: use this to surface business-level metadata at a glance — for example, whether a page targets NHS or Private patients.

seofields({
  healthDashboard: {
    licenseKey: 'SEOF-XXXX-XXXX-XXXX',
    getDocumentBadge: (doc) => {
      if (doc.services === 'NHS')
        return { label: 'NHS', bgColor: '#e0f2fe', textColor: '#0369a1' }
      if (doc.services === 'Private')
        return { label: 'Private', bgColor: '#fef3c7', textColor: '#92400e' }
    },
  },
})