Last updated: May 2026
If you've been building on WordPress for a while, you've probably run into the ceiling. The theme system works until it doesn't. Plugin conflicts slow things down. The frontend feels constrained by what WordPress can render. At some point the question becomes: what if WordPress just handled the content, and something faster handled everything the user actually sees?
That's the idea behind headless WordPress. And React is the most widely used frontend for doing it.
This guide covers how the architecture works, the two main approaches to connecting WordPress and React, when headless is the right call and when it isn't, and how to get a working setup deployed. I've used this stack on real client projects and I'll share what actually matters in practice, not just what the documentation says.
What headless WordPress actually means
Traditional WordPress is a monolithic system. It manages content, processes requests, and renders HTML all in the same place. When someone visits a page, WordPress queries the database, processes PHP templates, and delivers a complete HTML document. It works well for most sites, but it ties your frontend experience directly to what WordPress's theme system can produce.
A headless setup changes the architecture. WordPress still manages all your content through the familiar admin panel. But instead of rendering the frontend itself, it exposes that content through an API. A separate React application fetches that data and handles everything the user sees.
The result is a clean separation: WordPress as the content backend, React as the presentation layer. Your editorial team keeps the CMS they know. Your development team gets the frontend flexibility of a modern JavaScript framework.
When headless is the right call
Headless WordPress is not the right choice for every project. It adds architectural complexity and requires managing two systems instead of one. Before going down this path, the use case should justify it.
Headless tends to be the right call when:
Performance is a hard requirement. React's component-based rendering and the ability to deploy the frontend to a CDN edge network through Vercel or Netlify means significantly faster load times than a traditional WordPress theme. If Core Web Vitals are a business priority, headless gives you more control over performance than any WordPress theme can.
You're delivering content to multiple surfaces. If the same content needs to feed a website, a mobile app, and a third-party integration, a headless CMS with a clean API layer is the right architecture. WordPress becomes the single source of truth and each consumer fetches what it needs.
The frontend requirements are too complex for traditional themes. Highly interactive interfaces, single-page application behavior, custom animations, and complex state management are all easier to build in React than in a WordPress theme.
Your team is split between content editors and frontend developers. Headless lets each team work in the tools they're best in without stepping on each other. Editors work in WordPress admin. Developers work in React.
When headless is the wrong call
This is the part most tutorials skip, but it matters.
If your site is primarily a marketing site or blog that a non-technical team needs to manage, headless removes access to the WordPress plugin ecosystem that makes content management fast. Things like visual page builders, form plugins, and SEO tools either don't work in a headless setup or require significant workarounds.
If you don't have a dedicated frontend developer, the ongoing maintenance burden of two systems is real. WordPress updates, React dependency updates, API compatibility, and deployment pipelines all need attention separately.
If speed to launch is the priority and the frontend requirements are straightforward, a well-built WordPress theme with good hosting will outperform a rushed headless implementation on every metric that matters.
Go headless when the frontend complexity or multi-platform requirements justify it. Don't go headless because it sounds modern.
The two main approaches: REST API vs WPGraphQL
Once you've decided headless is right for your project, you have two main options for how React talks to WordPress.
WordPress REST API
The REST API is built into WordPress core. No additional plugins required. It exposes your posts, pages, custom post types, taxonomies, and media through standard JSON endpoints.
https://your-site.com/wp-json/wp/v2/posts
https://your-site.com/wp-json/wp/v2/pages
https://your-site.com/wp-json/wp/v2/categories
In your React application, you fetch this data using the Fetch API or Axios:
The REST API is the simpler starting point and works well for most projects. The main limitation is over-fetching: each endpoint returns a fixed set of fields whether you need them all or not.
WPGraphQL
WPGraphQL is a free plugin that adds a GraphQL API to WordPress. Instead of fixed endpoints that return everything, GraphQL lets you request exactly the fields you need in a single query.
This is more efficient for complex content models, particularly when you're fetching nested data like posts with their categories, featured images, and custom fields in a single request. The tradeoff is a steeper setup curve and an additional plugin dependency.
For most projects, start with the REST API. Move to WPGraphQL if you're dealing with complex content relationships or performance becomes a concern at scale.
Setting up Advanced Custom Fields for structured content
One of the practical challenges in headless WordPress is that default post fields are limited. Title, content, date, and featured image cover the basics, but real projects almost always need custom fields: pricing, specifications, team member data, case study metrics, and so on.
Advanced Custom Fields (ACF) solves this. You define custom field groups in the WordPress admin, and ACF exposes those fields through the REST API or WPGraphQL automatically.
To make an ACF field group available via the REST API, enable the option in the field group settings. Your custom fields then appear in the API response alongside the default fields:
https://your-site.com/wp-json/wp/v2/posts?acf_format=standardFor WPGraphQL, install the WPGraphQL for ACF plugin, which registers your field groups in the GraphQL schema and makes them queryable alongside other post data.
ACF is the most practical way to manage structured content in a headless WordPress setup without writing custom post meta code from scratch.
Handling CORS
When your React frontend is on a different domain than your WordPress backend, you'll run into CORS errors. The browser blocks requests from one origin to another unless the server explicitly allows it.
Fix this by adding CORS headers to your WordPress installation. The cleanest approach is in your .htaccess file:
Replace the origin with your actual frontend URL. If you're in development, you can temporarily set it to * but lock it down to your specific domain before going to production.
Alternatively, several WordPress plugins handle CORS configuration without touching server files if you don't have direct access to .htaccess.
Authentication
Public content like blog posts and pages doesn't require authentication. Your React app can fetch it directly from the REST API without any credentials.
Protected content, user-specific data, and any write operations (creating or updating posts) require authentication. The two most common approaches are:
JWT Authentication. Install the JWT Authentication for WP REST API plugin. After a user logs in through your React app, WordPress returns a token. Your app includes that token in the Authorization header of subsequent requests.
Application Passwords. Built into WordPress core since version 5.6. Generate an application password in the WordPress user profile, then include it as a Basic Auth header in your API requests. Better suited for server-to-server communication than user-facing login flows.
For most headless setups where content is publicly readable, you won't need authentication at all until you're building features that require user accounts.
Deployment
The most common deployment pattern for headless WordPress in 2026 is:
WordPress backend on managed WordPress hosting. WP Engine, Kinsta, and Pressable all handle WordPress-specific infrastructure well. Your editors never see anything change.
React frontend deployed to a CDN-based hosting platform. Vercel and Netlify are the standard choices. Both connect directly to your Git repository and deploy automatically on every push. Your React build runs at the edge, close to your users, which is where the performance gains come from.
Set your environment variables in your React deployment to point to your production WordPress API URL:
REACT_APP_WP_API=https://your-wordpress-site.com/wp-json/wp/v2
Keep your development environment pointing to a local or staging WordPress instance so you're not making live API calls during development.
A note on Next.js
If you're starting a new headless WordPress project in 2026, it's worth considering Next.js rather than plain React. Next.js is built on React but adds server-side rendering, static site generation, and built-in routing out of the box.
For headless WordPress specifically, server-side rendering matters for SEO. A pure React single-page application requires additional configuration to make content crawlable. Next.js handles this by default, which is one less problem to solve.
I covered this in more depth in my post on integrating HubSpot with Next.js, which goes into how the same architectural thinking applies when you're connecting a React frontend to any backend API.
Summary
Headless WordPress with React gives you a clean separation between content management and frontend experience. WordPress handles what it does well: content editing, user management, and media. React handles what it does well: fast, interactive user interfaces.
The REST API is the right starting point for most projects. Add WPGraphQL if your content model gets complex. Use ACF for structured custom fields. Handle CORS early so it doesn't slow you down later. Deploy the frontend to Vercel or Netlify for the performance gains that make headless worth the extra architecture.
The decision to go headless should always come back to whether the frontend requirements justify the added complexity. When they do, this stack is one of the most capable combinations available for building on WordPress today.
Frequently Asked Questions
It depends entirely on the project. Headless gives you more frontend flexibility and better performance potential, but it requires more technical resources to build and maintain. For most marketing sites, blogs, and straightforward business websites, a well-built traditional WordPress theme with good hosting will perform well and cost less to operate. Headless makes sense when you have complex frontend requirements, multi-platform content delivery needs, or a dedicated development team.
The REST API works well for most projects and requires no additional plugins. WPGraphQL is worth adding when you have complex content relationships and want the efficiency of requesting only the fields you need. Start with the REST API and add WPGraphQL if you hit its limitations.
Some will, some won't. Plugins that extend the WordPress admin or add backend functionality generally work fine. Plugins that output frontend code through shortcodes or modify theme templates won't work because headless bypasses the WordPress frontend entirely. SEO plugins like Yoast can still manage metadata, but you'll need to fetch and render that metadata in your React application manually.
It can be, but it requires more intentional configuration than traditional WordPress. A pure React single-page application is harder for search engines to crawl. Using Next.js with server-side rendering or static site generation solves this. You'll also need to handle meta tags, Open Graph data, and structured markup in your React application rather than relying on a plugin to do it automatically.
The terms are often used interchangeably. Technically, a fully headless setup means WordPress has no frontend at all. A decoupled setup may still use the WordPress frontend for some pages while using React for others. In practice, most people use both terms to mean the same thing: WordPress as the backend, a JavaScript framework as the frontend.
Not in any practical way. Page builders generate frontend markup that gets bypassed in a headless architecture. If your team relies on a visual page builder for content editing, headless WordPress is the wrong choice. ACF with flexible content fields is the closest equivalent that works reliably in a headless setup.
Building a headless WordPress site and want a second opinion on the architecture? Get a free site teardown and I'll tell you exactly what I'd do differently.