Advanced Custom Fields (ACF)

ACF is one of three patterns Matters AI uses to store editor-controlled content. Knowing when ACF is the right tool is more important than knowing how to use it — the previous agency over-used ACF and left 13 dead field groups behind. This page is the canonical guide.

When to use ACF#

There are three patterns in this codebase:

ACF's sweet spot is the third pattern — one to five small fields on an existing entity (post, page, category, user) where editors need to override per-instance without writing code.

Use ACF when#

• The field is specific to one entity instance (this post needs a PDF; that one doesn't)
• The data is structurally simple (URL, toggle, image, short text)
• Marketing/sales needs to update it without a deploy
• You'd otherwise need to ask devs to commit a value mapping

Don't use ACF when#

• The data is a large structured page schema → use a CPT with content JSON instead (the CPT pattern)
• The data is site-wide and rarely changes → hardcode it
• You'd need more than ~5 fields per group on one entity → escalate to a workspace module
• The data needs complex validation, workflows, or relations → build a proper admin UI

The 5-field guardrail#

If you're adding more than ~5 fields to a single ACF group, that's the signal to step back and ask: should this be a workspace module instead? Bigger ACF groups are how the previous agency ended up with 13 dead groups — they made every page template an ACF schema. Don't repeat it.

Setup checklist for a new ACF field#

When you add a new ACF field group, in WP Admin → ACF → Field Groups → Add New:

Then, in your field group:

• Field Name must be snake_case (this is the key in REST: post.acf.<name>)
• Field Type should match the data: URL, Text, True/False, Image, etc.
• Set Required only if literally every existing entity has data

How the Next.js side reads ACF#

The base Post type in lib/wordpress.d.ts carries an optional acf object:

export interface Post extends WPEntity {
  // ...
  acf?: {
    author_name?: string;
    author_position?: string;
    pdf_download_url?: string;
    [key: string]: any;
  };
}

The index signature lets you read any field without re-typing — but add new fields to the explicit list so they're discoverable. Always guard with optional chaining:

const url = typeof post.acf?.pdf_download_url === "string"
  ? post.acf.pdf_download_url
  : null;

Live field groups (alive — do not deactivate)#

These are the only ACF groups currently consumed by the Next.js app as of 2026-05-29:

If you add a new ACF group that becomes live, add a row here.

Blog Overrides — setup#

Single per-Post field group covering schema overrides, listing visibility, TOC layout, and per-post author social links.

Group settings:

Fields (use ACF Tab fields between sections for the post-edit UX):

Resolution order for the schema fields on each request:

1. If faq_schema_override parses to a valid object → that block is emitted (auto-FAQ skipped).
2. Else, if disable_auto_faq_schema is false (or unset) and the post body contains any matters-faq-block, the auto-extracted FAQPage JSON-LD is emitted.
3. Every valid object in custom_jsonld is then appended.

Invalid/unparseable JSON is silently ignored (no broken pages).

Category Customisation — setup#

Per-category landing-page overrides. Scoped to the Category taxonomy (not Post), so it must be a separate field group.

Group settings:

Fields:

Edit any category in WP Admin → Posts → Categories → click a category → fields show in the right panel.

Dead field groups (deactivation queue)#

These 13 groups returned zero hits across the Next.js codebase when audited on 2026-05-29. They are leftovers from the previous agency's WordPress-as-frontend setup, where every page template was an ACF schema. After migrating to Next.js, all the page data was hardcoded or moved to CPTs — but the ACF groups were never cleaned up.

Deactivation playbook#

Do not delete groups yet. Deletion is one-way; deactivation preserves the data on each post (in wp_postmeta) and the field definitions, so reactivation is risk-free.

The two-week soak window planned below (deactivate → 2026-06-12) has now elapsed. WordPress ACF state lives outside this repo, so confirm the current Inactive/Deleted status directly in WP Admin → ACF → Field Groups before acting. Treat the steps below as the standing procedure for any group still pending cleanup.

Process:

1. Deactivate: open each group in ACF → Field Groups → toggle to Inactive.
2. Smoke-test the critical surfaces immediately:
   • Homepage
   • A blog post detail page
   • A case-study post detail page
   • /about-us
   • /use-case/<any>
   • /platform/why-matters
   • /platform/how-it-works
   • /industry/<any>
3. Soak ~two weeks after deactivating (the original cut-over targeted 2026-06-12). Watch Sentry + manual spot-checks.
4. Delete only if no breakage reported during the soak. Update this page when groups are deleted.

Deactivation order (lowest risk first)#

1. Services page template, Header, Hero Section Footer, Contact us, Stack
2. Why Matters, How it works, About us, Homepage, Use Case Template, Testimonials, Footer
3. Post category bg color
4. Single post ⚠️ — last, because every blog post has data here. Reactivation preserves data, but mistakes are easier to spot if this is touched alone.

Worked example — Case Study Resources#

This is the canonical "right size for ACF" implementation. Follow this when adding a new ACF field.

WP setup#

Editor flow#

1. Open the PayU case-study post (or any post in the Case Studies category).
2. A new "Case Study Resources" section appears below the editor.
3. Paste /downloads/payu-case-study.pdf (or a WP media library URL).
4. Update post. Done.

Code flow#

// app/[...slug]/page.tsx
const downloadUrl = isCaseStudy
  ? typeof post.acf?.pdf_download_url === "string"
    ? post.acf.pdf_download_url
    : null
  : null;

return <BlogPostTemplate ... downloadUrl={downloadUrl} ... />;

Before this change, the same value lived in a static lib/case-study-downloads.ts map. Devs had to commit + deploy for every new case-study PDF. Now editors update WP → next revalidation pulls the new URL automatically.

Future ACF candidates#

Documented for visibility; not built yet as of 2026-05-29:

Add new rows here when you're considering adding ACF. Don't slip into the old-agency pattern of one ACF group per page template.

Related#

• CPT-Backed Module Pattern — when not to use ACF
• Snippet Generators — also editor-controlled content, but stored inside the post body rather than as ACF metadata
• Content & CMS — how WordPress updates propagate to Next.js
• SEO & Analytics — where structured-data overrides matter most