What is Headless WordPress?

What is Headless WordPress?

Headless WordPress is when you rip out the entire PHP theme layer and use WordPress purely as a content API. Editors still log into the familiar WP admin to write posts and build pages, but the frontend that visitors see? That's a completely separate Next.js, Astro, or Nuxt app fetching content via REST or GraphQL.

The WordPress REST API shipped in core back in December 2016 (version 4.7). Most production headless setups use WPGraphQL instead—it's a plugin, but it lets you request exactly the fields you need instead of getting back everything and filtering client-side.

We've shipped this on 50+ client projects. It's our default for content-heavy marketing sites where editorial teams need WordPress's familiar interface but the site absolutely has to pass Core Web Vitals. Lighthouse scores consistently land above 90 because you're not loading WordPress's theme engine, plugin-injected scripts, or executing PHP on every request.

How it works

Traditional WordPress: visitor hits a URL, WordPress runs PHP, queries MySQL, assembles HTML using the active theme, returns the page.

Headless: that entire rendering chain gets replaced.

Here's the stack:

1. WordPress backend — Runs on standard LAMP/LEMP or managed hosting (WP Engine, Kinsta). Editors use Gutenberg or ACF. No public theme is active—sometimes we leave Twenty Twenty-Three installed just so WordPress doesn't complain.
2. API layer — Content exposed via /wp-json/wp/v2/ (REST API) or /graphql (WPGraphQL). We use WPGraphQL on every project now—it cuts payload sizes in half compared to REST.
3. Frontend application — Next.js App Router is most common. Fetches content at build time (SSG) or request time (SSR/ISR). ISR with on-demand revalidation via webhook is the sweet spot for most sites.
4. Deployment — Frontend lives on Vercel, Netlify, or Cloudflare Pages. The WordPress instance is locked down—never directly exposed to end users.

Minimal WPGraphQL query:

query GetPosts {
  posts(first: 10) {
    nodes {
      title
      slug
      excerpt
      date
      featuredImage {
        node {
          sourceUrl
        }
      }
    }
  }
}

The frontend consumes this at build or request time and renders it with full control over markup and styles. No wp_head() dumping 40 lines of metadata. No jQuery loaded by some plugin you installed three years ago. No mystery scripts.

When to use it

Headless WordPress isn't always the right call. Here's the honest breakdown.

Use headless when:

• Your editorial team already knows WordPress and retraining on Contentful isn't happening
• You need pixel-perfect, highly interactive frontends (complex animations, app-like UX)
• Core Web Vitals directly impact your SEO rankings or ad revenue
• You're serving content to multiple channels (web, native apps, digital signage, Alexa skills)
• You've got 10,000+ pages and need static generation with incremental rebuilds

Skip headless when:

• It's a simple blog or brochure site—traditional WordPress with a lightweight theme ships faster
• You rely on frontend-heavy plugins (WooCommerce storefront, BuddyPress, membership plugins with gated UI)
• Your team doesn't have JavaScript framework experience for ongoing maintenance
• Budget is tight—headless means paying for WordPress hosting and frontend hosting, plus the dev complexity

The first time I pitched headless to a client with a 12-page marketing site, they asked why we couldn't just use GeneratePress. They were right. If you don't have a clear performance problem or multi-channel distribution need, headless adds overhead you won't recoup.

Headless WordPress vs alternatives

Our stack at Social Animal: WordPress + ACF Pro + WPGraphQL on WP Engine, Next.js 15 App Router on Vercel. Astro for purely static marketing sites where there's zero dynamic behavior.

Real-world example

B2B SaaS company. 4,000 blog posts, 200 landing pages. Traditional WordPress theme scoring 38 on Lighthouse with a 4.2s LCP. Organic traffic had flatlined.

We set up WPGraphQL and ACF Pro for structured content. Built the frontend in Next.js 15 with ISR on a 60-second revalidation window. Deployed to Vercel. Editors kept using the exact same WordPress admin—most didn't realize anything changed.

Post-launch: Lighthouse performance hit 96. LCP dropped to 1.1s. Organic traffic up 34% over four months, almost entirely because the site started passing Core Web Vitals thresholds and Google rewarded it.

Build times for 4,000+ pages: under 3 minutes with parallel static generation. The old WordPress theme took 11 seconds just to render the homepage.