Modern web development often uses a headless WordPress setup, where WordPress powers content management and a separate React front-end displays that content. In fact, WordPress still powers over 40% of all websitesblog.devgenius.io, and many developers are combining it with React for speed and flexibility. In a headless approach, WordPress acts purely as a CMS exposing content via APIswordpress.com. A React front-end then fetches content (via the WordPress REST API or GraphQL) and renders it. This decoupled WordPress website model offers scalability and rich UI possibilities.
In this guide, we’ll introduce 10 essential tools and walk through building a headless site step by step. We’ll cover setting up WordPress for headless use, creating a React front end, fetching and displaying posts, and deployment tips. Ready to get started? Let’s dive in and see how you can build a headless website with WordPress and React.
What is Headless WordPress?
Headless WordPress (also called decoupled WordPress) means separating the backend (content management) from the frontend (display). In a traditional site, WordPress themes and templates handle everything. In a headless setup, WordPress only provides content via APIs, and any frontend tech (like React) handles presentationwordpress.comkanopi.com.
“In a Headless setup, WordPress acts purely as a CMS that exposes content via an API, allowing you to choose any front-end technology to power the user-facing site or app.”wordpress.com
This lets us choose the best tools for each job. For example, you could have a React app, a mobile app, and even a static site all consuming the same WordPress data. Tools like the WordPress REST API (built into WordPress coredeveloper.wordpress.org) or WPGraphQL (a plugin providing a GraphQL endpointwpgraphql.com) serve content to your app. In short, headless WordPress means WordPress is a content provider, and your React front-end takes it from there.
Why Use React with Headless WordPress?
There are many reasons to pair React with headless WordPress. React is “a JavaScript library for building user interfaces”legacy.reactjs.org that makes creating interactive UIs painless. By using React on the front end, you can leverage modern development workflows and improve performance. For example, decoupling can yield faster, more efficient websites, since your site can be served as optimized static assets or with only the code neededkanopi.com. React’s component-based nature (so you can design reusable UI pieces) and virtual DOM make your app snappy and responsive.
From a developer’s perspective, the developer experience is enhanced. Teams can work on the WordPress backend and the React frontend independently (often even in parallel) without stepping on each other’s toesblog.devgenius.io. You’ll use tools like Node, npm, Babel, and hot-reloading that React supports, instead of dealing with PHP templates. Also, a headless setup means greater design flexibility – you’re not constrained by WordPress themes or PHP template limitationskanopi.com. You can use any styling framework or modern build tools (see Vite below) to craft a unique UI.
Headless + React also makes multi-channel publishing easy. The same WordPress content can power a React web app, a React Native mobile app, or even IoT devices, all via the same APIskanopi.comkanopi.com. In short, React’s ecosystem and WordPress’s content management together give you a powerful, flexible platform.
How to Set Up a Headless WordPress Environment
Before coding, set up your WordPress backend for headless mode. A local dev environment is helpful. LocalWP (by WP Engine) is a free, popular tool for spinning up local WordPress siteslocalwp.com. Install LocalWP and create a new site with one click. You’ll have PHP, MySQL, and WP ready without manual config. (Other tools like MAMP or Docker could work too, but LocalWP is beginner-friendly.)
Once WordPress is running locally, install the plugins you need. If you want GraphQL, install WPGraphQL – a free plugin that adds a /graphql endpoint to WordPresswpgraphql.comkinsta.com. You can find it on WordPress.org or via your dashboard. WPGraphQL often comes with a built-in GraphiQL IDE (under the “GraphQL” admin tab) for testing queries. If you prefer REST, you don’t need extra plugins – the WordPress REST API is already built indeveloper.wordpress.org. Just ensure your content (posts, custom post types, etc.) has 'show_in_rest' => true when registered, which makes it accessible at /wp-json/wp/v2/... endpoints.
You’ll also want tools for development and testing. VS Code is a popular code editor – install it to write JavaScript, JSX, and to browse your project files. (Any code editor works, but VS Code has great React/JS support.) For API testing, tools like Postman (or Insomnia) let you quickly call your WordPress endpoints and inspect the JSON responses. For example, you can use Postman to GET http://localhost/wp-json/wp/v2/posts and see your posts data.
Creating a React Front-End
Now create the React app that will consume WordPress data. You can use Vite or Create React App (CRA) to scaffold the project. Vite is a modern build tool that offers a faster dev server and leaner buildsvite.dev. To start with Vite, run:
bashCopyEditnpm create vite@latest my-app -- --template react
cd my-app
npm install
npm run dev
This sets up a new React project in my-app/ and runs a dev server at http://localhost:3000. If you prefer CRA, you could do npx create-react-app my-app instead. Whichever you choose, your directory is now ready for coding. Open it in VS Code.
Install some essential packages. For example, install React Router for routing:
bashCopyEditnpm install react-router-dom
In your src/App.js, you might add:
jsxCopyEditimport { BrowserRouter, Routes, Route } from 'react-router-dom';
import Home from './Home';
import PostDetail from './PostDetail';
function App() {
return (
<BrowserRouter>
<Routes>
<Route path="/" element={<Home />} />
<Route path="/post/:id" element={<PostDetail />} />
</Routes>
</BrowserRouter>
);
}
This sets up a React front-end where / shows a list of posts and /post/:id shows a single post.
Another tool: install Axios (or use the built-in fetch) to make HTTP requests from React. For example:
bashCopyEditnpm install axios
Then in your components, you can import Axios to call the WordPress API.
Throughout development, VS Code will be your companion – it highlights JSX syntax, has Git integrations, and many useful extensions (like ESLint, Prettier, React snippets, etc.). Use it to write components, style your UI, and manage your project.
Fetching WordPress Content via REST API or WPGraphQL
With WordPress set up and the React app ready, fetch your content. You have two main options: the WordPress REST API or WPGraphQL.
Using the REST API with Axios or fetch
The REST API exposes endpoints for posts, pages, categories, etc. For example, /wp-json/wp/v2/posts returns your posts in JSON. Here’s a simple React example using fetch:
jsxCopyEditimport { useEffect, useState } from 'react';
function Home() {
const [posts, setPosts] = useState([]);
useEffect(() => {
fetch('http://localhost/wp-json/wp/v2/posts')
.then(res => res.json())
.then(data => setPosts(data));
}, []);
return (
<div>
<h1>Blog Posts</h1>
{posts.map(post => (
<article key={post.id}>
<h2>{post.title.rendered}</h2>
<div dangerouslySetInnerHTML={{ __html: post.excerpt.rendered }} />
</article>
))}
</div>
);
}
This code retrieves the list of posts and saves them in state, then displays each title and excerpt. Note how we use dangerouslySetInnerHTML to render HTML excerpts safely. If you prefer Axios, it would look like:
jsCopyEditimport axios from 'axios';
axios.get('http://localhost/wp-json/wp/v2/posts')
.then(response => {
console.log(response.data);
});
You can test these endpoints first in Postman or a browser to see the raw JSON. The REST API is uniform and built into WordPressdeveloper.wordpress.org, so it’s reliable and doesn’t need extra setup.
Using WPGraphQL
Alternatively, WPGraphQL provides a single /graphql endpoint for more flexible querieskinsta.com. After installing WPGraphQL, you can query exactly the fields you want. For example:
jsCopyEditconst query = `
query {
posts {
nodes {
id
title
excerpt
date
}
}
}
`;
fetch('http://localhost/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ query })
})
.then(res => res.json())
.then(data => {
console.log(data.data.posts.nodes);
});
This POST request asks for posts with id, title, excerpt, and date. You’ll get a JSON response with exactly those fields, which can simplify your React code. (WPGraphQL also has a GraphiQL IDE in the WP admin if you want to build queries visually.)
Whichever API you choose, remember: WPGraphQL is a GraphQL-based plugin that “provides an extendable GraphQL schema and API for any WordPress site”wpgraphql.com. It uses a single endpoint to fetch data efficientlykinsta.com. The REST API, on the other hand, has multiple endpoints (e.g. /posts, /comments)kinsta.com. Use whatever fits your project best. (Pro tip: search for “WPGraphQL tutorial” to find step-by-step guides for GraphQL setups.)
Displaying Posts in React
Once you have fetched data, the next step is rendering it in your React components. For instance, using the REST API example above, we mapped over posts and printed title and excerpt. If you’re using React Router, you could also make each title a link to a detail page:
jsxCopyEditimport { Link } from 'react-router-dom';
{/* inside the map */}
<h2>
<Link to={`/post/${post.id}`}>{post.title.rendered}</Link>
</h2>
Then your PostDetail component (at /post/:id) can fetch a single post by ID:
jsxCopyEditfunction PostDetail({ id }) {
const [post, setPost] = useState(null);
useEffect(() => {
axios.get(`http://localhost/wp-json/wp/v2/posts/${id}`)
.then(res => setPost(res.data));
}, [id]);
if (!post) return <p>Loading...</p>;
return (
<article>
<h1>{post.title.rendered}</h1>
<div dangerouslySetInnerHTML={{ __html: post.content.rendered }} />
</article>
);
}
If using WPGraphQL, the component might use a similar approach with a GraphQL query. The idea is the same: fetch data and set state, then let React re-render.
For styling and structure, you can use any CSS framework or library you like. Many developers use component libraries like Material-UI or Bootstrap, but even plain CSS or styled-components works. Remember the React Router setup from the previous section will handle navigation, and your Axios or fetch calls bring in dynamic content.
Authentication and Deployment Tips
Authentication: In many headless apps, the front end is public and shows public posts with no auth. But if you need protected content (private posts, user data, etc.), you’ll need to handle auth. WordPress supports Application Passwords (since WP 5.6) for the REST API, which is an easy way to authenticate API requests. There are also JWT (JSON Web Token) plugins for WordPress REST API or GraphQL. For example, the WPGraphQL JWT plugin can secure your GraphQL endpoint. If you install a JWT plugin, your React app would include a login step to get a token, then include that token in request headers. This is more advanced, but worth mentioning.
Deployment: When ready to deploy, your WordPress backend can go on any PHP host or managed WP host (WP Engine, Kinsta, etc.). Your React app becomes a static or server-rendered frontend. A popular choice is to build the React app and host it on a platform like Netlify or Vercel. These services work great with React – you just connect your Git repository, and they automatically build and publish your site. For example, Netlify has quickstart guides for React apps (you can deploy in “less than 30 seconds”netlify.com).
On Netlify/Vercel, remember to set the WP API base URL as an environment variable if your WordPress site URL is different in production. Both platforms offer free SSL, CDN, and continuous deploy on push. For the backend, if you need scaling, consider using WordPress.com (Atlas) or WP Engine’s headless offerings, though a simple VPS or shared host often works.
Other handy tools: Postman, as mentioned, can test your APIs any time. And if you’re deploying frequently, tools like Vercel CLI or Netlify CLI can streamline your workflow.
Pros and Cons of Headless WordPress
Building a headless WordPress + React app has trade-offs:
- Pros:
- Flexibility: You are free to build any interface with React (or any framework)kanopi.com. No theme restrictions.
- Performance: Decoupled setups can be faster. By serving static assets or optimized bundles, content loads quicklykanopi.com.
- Multi-Channel: Same content powers web, mobile, and more. WordPress content can be delivered to any platform via APIkanopi.com.
- Security: With the frontend separate, there’s a smaller attack surface on the backend. (For example, bots can’t easily exploit frontend themes to get at the database.)kanopi.com.
- Cons:
- Complexity: You maintain two systems (the WordPress CMS + the React app). That means more maintenance and setup timekanopi.com.
- Developer Needs: A traditional WP site can be managed with basic knowledge, but headless often requires JavaScript expertise. You might need to hire a developer to build the React partkanopi.com.
- Plugin Support: Many WP plugins assume a normal theme. In a headless setup, things like visual page-builders or some shortcode-based plugins won’t just “show up” – you may need to rebuild that functionality in React or find workaroundskanopi.comkanopi.com.
- Preview & WYSIWYG: Editors might find it less obvious how the site will look, since changes aren’t immediately visible in a theme. (Some tools exist to preview headless content, but it’s extra work.)
Whether headless is “worth it” depends on your project. Large or dynamic sites benefit most, while small blogs may be fine the old way. But with tools like WPGraphQL and modern hosting, headless development has never been more accessible.
Conclusion
Combining React with headless WordPress lets you build a headless website that has the best of both worlds: WordPress’s ease of content management and React’s modern front-end capabilities. We covered how to set up a headless environment (using tools like LocalWP, WPGraphQL, and GraphiQL), how to create a React front-end (with Vite or CRA, VS Code, React Router, Axios), and how to fetch and display posts via the WordPress REST API or WPGraphQLdeveloper.wordpress.orgkinsta.com. We also discussed deployment (Netlify, Vercel) and pros/cons of this architecture.
Now it’s your turn – try building this on your own! Follow a WPGraphQL tutorial or read more on the WordPress REST APIdeveloper.wordpress.org to master the details. You might also like our other guides on modern WordPress development. Are you ready to build your first decoupled WordPress website?
Experiment with these tools, tweak the code, and see what you can create. If you found this helpful, subscribe or check out our other tutorials for more tips on WordPress and React development. Happy coding!