Explainers · Explainer
What Is WordPress Headless Cms? Explained

Short answer
Headless WordPress means using WordPress only as a back end to write and store content, then delivering that content through the REST API or GraphQL to a separate front end, often built with React or Next.js. You gain front-end freedom but lose many theme and plugin features.
Key takeaways
- Headless WordPress removes the theme and keeps the admin and database.
- Content travels as JSON through the REST API or WPGraphQL.
- Front ends are often built with Next.js, Astro or Nuxt.
- Many front-end plugins stop working without custom work.
- It suits teams with developers, not most small sites.
What is WordPress as a headless CMS?
Headless WordPress means you use WordPress only to store and manage content, then send that content through an API to a separate front end built with another tool, such as React or Next.js.
In a normal WordPress site, WordPress does two jobs. It stores your content in the database, and it builds the pages visitors see using your theme.
In a headless setup, you cut off the head, which is the theme and front-end output. WordPress keeps the body: the admin, the editor, users, media and the database. A separate application asks WordPress for content and decides how to display it.
The term CMS just means content management system. So a headless CMS is a content manager with no built-in presentation layer.
How does headless WordPress work?
The front end requests content from WordPress through the built-in REST API or a GraphQL plugin, receives it as JSON data, and renders the pages itself.
A typical flow looks like this:
- Editors write and publish posts in the usual WordPress dashboard.
- The front-end app, often built with Next.js, Astro, Nuxt or Gatsby, calls WordPress for data.
- WordPress returns posts, pages, menus and media as JSON.
- The front end turns that data into HTML pages, either at build time or on request.
- Visitors load the front-end app, usually from a separate host or CDN, not from WordPress.
WordPress has shipped the REST API in core since version 4.7. Every site already exposes endpoints such as /wp-json/wp/v2/posts. Our guide on how to use the WordPress REST API shows how to query them.
Many headless projects prefer GraphQL instead. The free WPGraphQL plugin adds a GraphQL endpoint so the front end can ask for exactly the fields it needs in one request.
What is the difference between headless and traditional WordPress?
Traditional WordPress builds pages with a PHP theme on the same server, while headless WordPress hands content to a separate app that builds the pages.
| Area | Traditional WordPress | Headless WordPress |
|---|---|---|
| Front end | PHP theme | Separate JavaScript or static app |
| Hosting | One server | WordPress host plus front-end host |
| Plugins affecting the front end | Work out of the box | Often need custom work |
| Preview and editing | Built in | Needs extra setup |
| Developer skills | PHP, HTML, CSS | JavaScript framework, APIs |
| Content reuse across apps | Limited | Easy, via the API |
| Typical cost | Lower | Higher build and upkeep |
For a longer side-by-side look, read headless WordPress vs traditional.
Why do people use WordPress as a headless CMS?
Teams go headless for front-end freedom, faster page delivery from static or edge hosting, content reuse across apps, and a smaller attack surface on the public site.
The main reasons:
- Modern front-end tools. Developers can use React, Vue or Svelte and their whole ecosystem.
- Speed. Pre-built static pages served from a CDN load quickly, and the front end does not wait on PHP for each visit.
- One content source, many outputs. The same posts can feed a website, a mobile app, digital signage or a smart TV app.
- Security. The WordPress admin can sit on a separate, locked-down domain, so the public site has no wp-login page to attack.
- Familiar editing. Editors keep the WordPress dashboard they already know.
That last point is why WordPress is a popular headless choice. Many other headless CMS products need editors to learn a new interface.
What are the downsides of headless WordPress?
Headless WordPress costs more to build and maintain, breaks many front-end plugins, and makes previews, forms and SEO tools harder to set up.
This is the part that surprises site owners most. A lot of what makes WordPress easy depends on the theme layer you have just removed.
Common pain points:
- Plugins stop working on the front end. Page builders, sliders, form plugins and many SEO plugins output HTML through the theme. In headless, you rebuild those features or use their APIs.
- Previews need work. Showing drafts before publishing requires extra code or a framework that supports it.
- Two systems to host and update. You maintain WordPress and the front-end app separately.
- Developer dependence. Small content layout changes may need a developer rather than an editor.
- Build times. Static sites with thousands of pages may need incremental builds to stay quick.
For a small blog or business site, these costs usually outweigh the benefits.
What tools are used to build headless WordPress sites?
Most projects combine WordPress with the REST API or WPGraphQL on the back end and a JavaScript framework such as Next.js on the front end.
Popular pieces include:
| Tool | Role |
|---|---|
| WordPress REST API | Built-in JSON API for posts, pages, media and users |
| WPGraphQL | Free plugin adding a GraphQL API |
| Next.js | React framework for server-rendered and static sites |
| Faust.js | Toolkit that eases headless WordPress with Next.js, including previews |
| Astro, Nuxt, Gatsby | Other front-end frameworks with WordPress integrations |
| Advanced Custom Fields | Structured content fields, exposed through the APIs |
The Next.js documentation covers rendering and data fetching patterns on the front-end side. Faust.js is an open-source framework from WP Engine aimed at headless WordPress builds.
Our guide on using WPGraphQL covers the API side.
For the full project, follow building a headless WordPress site.
Is headless WordPress good for SEO?
It can be, as long as the front end renders full HTML on the server or at build time and you rebuild titles, meta tags, sitemaps and structured data yourself.
Search engines can render JavaScript, but sites that send complete HTML are simpler and more reliable to crawl. Most headless setups use server-side rendering or static generation for that reason.
The bigger SEO risk is losing what your SEO plugin used to do. In a traditional site, it prints meta titles, canonical tags and schema into the theme. In headless, the front end must request that data and output it.
Some SEO plugins expose their data through the REST API or have WPGraphQL extensions. Check your plugin's documentation before you commit to a headless build.
What is decoupled WordPress?
Decoupled WordPress is a close cousin of headless where WordPress still renders some pages itself while a separate front end handles others, or where the theme stays available as a fallback.
The terms are often used loosely and interchangeably. A strict headless setup has no public WordPress front end at all. A decoupled or hybrid setup might keep WordPress for the blog while a JavaScript app runs the main marketing site.
Hybrid setups let teams adopt headless gradually instead of rebuilding everything at once.
When should you use WordPress as a headless CMS?
Headless makes sense for teams with developers who need a custom JavaScript front end, content in several apps, or very high traffic, and rarely for small sites run without developers.
Good fits:
- Large publishers and brands with in-house developers.
- Companies feeding the same content to a website and mobile apps.
- Projects that already use a JavaScript framework for the rest of the product.
- High-traffic sites that want static pages on a global CDN.
Poor fits:
- Small business sites, blogs and portfolios managed by non-developers.
- Stores that rely heavily on WooCommerce plugins, though headless commerce is possible with more work.
- Teams that want to change layouts often without code.
If you are unsure, a well-built traditional site with good caching gets most of the speed benefit at a fraction of the cost. Enterprise platforms such as WordPress VIP support both approaches if you outgrow standard hosting.
How do you get started with headless WordPress?
Start by confirming your content is reachable through the REST API or WPGraphQL, then build a small front-end prototype that fetches and shows a few posts.
A simple path for learning:
- Set up WordPress, locally or on a host.
- Visit /wp-json/wp/v2/posts on your site to see the REST API output.
- Optionally install WPGraphQL and test queries in its built-in IDE.
- Create a Next.js or Astro project and fetch a list of posts.
- Add single post pages, menus and images.
- Plan previews, SEO data and forms before going live.
If the REST API returns errors or is blocked, see how to enable the REST API in WordPress. Keeping the WordPress admin on a separate subdomain is a common pattern once the project goes live.
Frequently asked questions
Is headless WordPress faster than normal WordPress?
It can be, because static or edge-rendered pages skip PHP on each visit. But a well-cached traditional WordPress site is also very fast. Speed in headless depends heavily on how the front end is built, hosted and how much JavaScript it ships to the browser.
Do WordPress plugins work in a headless setup?
Back-end plugins such as custom fields, user roles and editorial tools still work. Plugins that output HTML on the front end, like page builders, sliders, forms and many SEO features, do not work automatically and need to be rebuilt or accessed through their APIs.
Do I need to know JavaScript to use headless WordPress?
Editors do not, because they still use the normal WordPress dashboard. But building and maintaining the front end needs a developer comfortable with a JavaScript framework such as React or Vue, plus APIs and modern hosting.
Can WooCommerce run headless?
Yes. WooCommerce has a REST API and Store API, and GraphQL extensions exist, so a custom front end can show products, carts and checkout. It takes significantly more development work than a theme-based store, especially for payments and plugin features.
Is headless WordPress the same as a static site?
Not exactly. Headless describes separating content from presentation. The front end may be a static site generated at build time, a server-rendered app or a mix. Static generation is simply one common way to build the front end of a headless WordPress project.
Sources
- REST API Handbook WordPress Developer Resources
- WPGraphQL WPGraphQL
- WPGraphQL plugin WordPress.org
- Next.js Docs Vercel
- Faust.js WP Engine
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


