Headless WordPress means using WordPress only as the content backend and building the front end separately, usually with a JavaScript framework that fetches content through the REST API or GraphQL. It makes sense when the same content feeds several channels, when the front end is a real application with its own JavaScript team, or when the site has to live inside a stack that is not PHP. It usually does not make sense for a slow marketing site or blog, because a well-cached WordPress theme is already fast and going headless means rebuilding features WordPress gives you for free. A good headless WordPress developer will tell you both sides before writing code.
I hear “should we go headless?” most often from teams whose real problem is performance. Sometimes the answer is yes. More often the site needs a working page cache and fewer scripts, and a rebuild would move the problem rather than fix it.
What is headless WordPress, technically?
In a traditional install, WordPress stores the content and also renders the HTML through a theme. In a headless setup, the theme is gone or ignored. Editors keep using wp-admin and the block editor, and a separate application requests the content and renders the pages.
Two APIs do most of the work. The REST API ships with WordPress core and exposes posts, pages, terms, users and custom post types that opt in. GraphQL comes from the WPGraphQL plugin, which lets the front end ask for exactly the fields it needs in one request. The front end can then render pages in three ways: generate static HTML at build time, render on the server for each request, or render in the browser. The first two send real HTML. The third sends a nearly empty page and builds it with JavaScript, which is a bad idea for any page you want indexed. I explain why in technical SEO starts in the server response.
When does headless WordPress make sense?
The good reasons are about architecture and teams, not speed:
- the same content goes to a website, a mobile app, in-store screens or partner feeds
- the front end is an application with logged-in state, dashboards or heavy interactivity, built by a team that already works in a JavaScript framework
- WordPress content has to appear inside an existing product that is not built on PHP
- the organization wants to swap the CMS or the front end later without rebuilding both
If one of these is your situation and you have the budget to run two codebases, headless is a reasonable choice. Larger organizations often reach this question while turning WordPress into a platform, which I cover in what enterprise WordPress actually means.
When does it not make sense?
- The only goal is speed. Caching and a lighter front end get there sooner and cheaper.
- The team is one or two people who know WordPress well and JavaScript frameworks less.
- Marketing builds landing pages in a page builder such as Elementor. Its layouts are rendered by the theme layer, so they do not carry over to a separate front end.
- The site depends on plugins that output front-end features, such as forms, SEO metadata, related posts or memberships.
- Nobody has budgeted for hosting, monitoring and maintaining a second application.
What do you lose when you go headless?
This is the part proposals tend to skip. Many things WordPress does through the theme have to be rebuilt or wired up by hand:
| Feature | Traditional WordPress | Headless |
|---|---|---|
| Post preview | Works out of the box | Needs authenticated requests and a preview route |
| SEO plugin output | Printed in the head automatically | Fetched from the API and rendered by your code |
| Forms, comments, memberships | Plugin handles markup and submission | Rebuilt in the front end, plugin used as a backend if it allows |
| Block styles and theme.json | Applied by WordPress | Reimplemented or parsed from block data |
| Cache invalidation | Caching plugin or host purges on publish | Webhook or revalidation you build and test |
| Redirects and sitemaps | Plugins manage them | Handled in the front end or at the edge |
| Hosting | One application | Two applications, two deploys, two sets of logs |
None of these are blockers. Each is a piece of work with a cost, and they add up. When a client shows me a headless quote, I check whether this list is in it.
Is headless WordPress faster?
Not automatically. Speed comes from two things: how fast the server returns HTML, and how much work the browser has to do afterwards. A traditional WordPress page served from a page cache or an edge cache already returns HTML quickly, because PHP and the database do not run on a cache hit. I explain the layers in page cache, object cache and edge cache.
On the browser side, a JavaScript front end can be lighter than a bloated theme, or much heavier. Frameworks that hydrate the whole page ship JavaScript for content that never changes, and that extra main-thread work is a common cause of poor INP. A headless site on server rendering with careful JavaScript can be very fast. So can a block theme. Measure your current field data before you assume the rebuild will help.
There is also a middle path. Core added the Interactivity API in WordPress 6.5 for interactive blocks without a separate front end, and speculative loading arrived in core in 6.8 to prefetch or prerender likely next pages. For many sites these cover the “feels like an app” goal while keeping the theme.
What does a headless WordPress developer actually build?
Being comfortable in React or another framework is half of the job. The other half is the WordPress side, and it is where I see most headless projects struggle:
- a content model with custom post types, taxonomies and fields designed for the API, not just for the editor
- API endpoints or GraphQL types that expose only what the front end needs, with caching in front of them
- authentication for previews and private content, for example with Application Passwords (in core since WordPress 5.6) or tokens
- a publish hook that rebuilds or revalidates the right pages, and only those
- SEO parity: titles, descriptions, canonicals, structured data, redirects and sitemaps
- an image pipeline with correct sizes, modern formats and dimensions to avoid layout shift
That mix of skills is why I think of headless as engineering work rather than theme work. I wrote about that difference in WordPress engineer vs developer, and the broader skill set in WordPress developer skills for 2026.
How do I decide?
Answer these honestly, in order:
- Does the content need to go anywhere other than the website?
- Is the front end an application, or a set of pages?
- Do you have people who will maintain a JavaScript front end for years, not only build it?
- Have you fixed caching and front-end weight on the current site and measured the result in field data?
- Does the budget include previews, SEO parity, forms and a second hosting bill?
Two yeses on the first three plus a yes on the last one make a real case. A no on question four means do that first.
Frequently asked questions
Is headless WordPress better for SEO?
It can match a traditional site if pages are rendered on the server or at build time and the SEO metadata is carried over. Client-side rendering and missing metadata make it worse. The architecture does not give you an SEO advantage by itself.
Can I go headless on part of the site?
Yes. A common setup keeps the marketing site on a normal theme and serves one application section, such as a product configurator or a customer area, from a separate front end that reads WordPress content.
REST API or GraphQL?
REST is in core and caches easily by URL. GraphQL needs a plugin and fetches nested data in one request with less overfetching. Pick the one your front-end team can cache and debug well.
If you are weighing a headless rebuild because the site is slow, find out why it is slow first. My WordPress performance audit separates what caching and front-end fixes can solve from what really needs a new architecture.