Headless WordPress – Complete Guide on How to Use it For Beginners

Headless WordPress - Complete Guide on How to Use it For BeginnersThe way we share information on the internet is constantly evolving. What seems to be the trend today, may become obsolete the next day. New technology trends such as headless WordPress make content management easier.

The WordPress platform comes with a lot of features out of the box. However, there are times when you need better performance and more flexibility on your website. In such a scenario, converting your WordPress site to a headless CMS is a great solution.

Don’t worry if the whole concept sounds like rocket science to you now. This guide will explain in detail what headless WordPress is all about. Then we will show you how to use it in WordPress.


  1. What is Headless WordPress?
  2. Pros and Cons of Headless WordPress
  3. How WP Headless Works
  4. How to Create a Headless WordPress Website
  5. Conclusion

What is Headless WordPress?

WordPress is one of the most popular content management systems available. A CMS is a complete software solution that provides the tools you need to manage your content online. This includes both frontend and backend implementation.

The backend takes care of retrieving your WordPress data from the database and sending that data to the user’s browser as content. The frontend is what your users see when they visit your WordPress site.

The concept of headless CMS was brought about in a bid to make sharing content easier. Headless CMS makes use of Microservices architecture. This means you are decoupling your WordPress installation into its frontend and backend components.

When decoupled, you can host your backend and frontend on separate servers. That gives you the flexibility to customize your website using any frontend framework.

WordPress core does not come with a headless CMS by default. However, using the REST API that comes with WordPress, you can turn your WP installation into a headless content management system.

The backend and the REST API retain the default WordPress interface. This means you can add content and perform other administrative tasks from the familiar WordPress dashboard.

On the other hand, the frontend is no longer dependent on WordPress. This means your WordPress theme is disabled, but you have more flexibility in choosing any frontend framework to build your website.

Examples of headless WordPress sites can be seen on some major brands such as Techcrunch, Facebook Brand Resources, Uber Brand Experience, NPM, amongst others.

Facebook Brand Resource Center 

Pros and Cons of Headless WordPress

Headless CMS architecture gives you more flexibility and control over the way you publish and display content on your website. However, it also has some drawbacks that are worth mentioning.

In this section, we will discuss some of the pros and cons of using headless architecture on your WordPress site. That way, you can make an informed decision on whether or not to implement it on your website.

Pros of Headless WordPress

Multichannel Content Publishing

Publishing content using traditional WordPress can be challenging because you are restricted to the number of platforms you can use. However, with headless architecture, you can publish your content on any platform while using a single WordPress backend.

The REST API makes it easy to integrate a WordPress site on platforms such as mobile apps, desktop applications, Single Page Applications (SPAs), and Progressive Web Apps (PWAs).

Programming Language Flexibility

Vanilla WordPress is built using PHP and a little JavaScript. This means, to become a WordPress developer, you need to be familiar with PHP.

After separating the backend from the frontend using headless WordPress, you can build your website using any programming language you are comfortable with.

This means you can combine WordPress with frameworks such as Django, React, Vue or Angular. In addition, you can build mobile applications using tools such as Flutter or Swift.

Improved Security

WordPress is a secure platform and also allows you to improve the security of your site using security plugins. However, WordPress uses a monolithic architecture where both frontend and backend sit on the same server. Your server is at risk with this type of implementation.

WP headless enables you to decouple your WordPress site and host the frontend on a separate server. This headless approach means only the frontend of your site is accessible to the general public. Therefore, that makes it difficult for hackers to access sensitive information on your site.

Fast Loading Website

When you separate your frontend from the backend, it relieves your server of some duties, thereby speeding up your site.

Additionally, when you integrate your WordPress site with a frontend library such as React, it will significantly improve your sites’ loading time.

This is because React uses Single Page Application (SPA) architecture that prevents sites from loading in the background when retrieving data from the server.

Easily Switch Frontend Framework

By decoupling your WordPress site, you can easily integrate it with any frontend framework as we mentioned earlier. In addition, it makes it easy to switch to a different framework because you don’t have to make any changes on the server.

It also simplifies the workload since you only have to be familiar with the frontend framework or hire a frontend developer.

Cons of Headless WordPress

WP headless appears to be the future of WordPress due to its numerous advantages. However, there are also drawbacks to using this system on your website. Here are a few of them;

Large Learning Curve

Before you can start using headless WordPress on your website, you need a solid understanding of how REST API works. In addition, you need to know how to fetch and consume data from REST endpoints.

This requires a lot of work and time to understand. Unless you are already a developer, you are better off using the vanilla version of WordPress. Otherwise, you would have to hire a professional developer.

No Live Preview and WYSIWYG Editor Functionality

WYSIWYG is short for What You See Is What You Get. In WordPress, this means the way your content appears on the Gutenberg block editor is the way it would appear on your site’s frontend.

This is one of the features that ranks WordPress as one of the best CMS in the world. In addition, WordPress also has a live preview feature that shows you how your site looks when editing or adding sections to your website.

If you decouple your WordPress CMS, you lose access to both the live preview and the WYSIWYG editor. This means you must manually check every change you make by previewing on the browser which can be time-consuming.

Requires Extra Technical Knowledge

Decoupling WordPress in most cases means you want to build your site manually. To build the frontend requires that you are familiar with at least one frontend framework.

If you are not tech-savvy, it may be difficult for you to use this technology on your website.

Also, before using WP REST API, you need to have some technical knowledge of how web technologies work in general.

No More Themes and Plugins

Themes and plugins make WordPress fun and easy to use, especially for beginners. When you switch to a headless WordPress platform, you lose access to these features.

This means you have to manually build out any functionality you want to have on your website, which can be complex and time-consuming as opposed to using plugins and themes.

In addition, implementing authentication will become complex since you have to build out the logic to authenticate users on your website.

High Maintenance Cost

Most times you would need to hire a frontend developer to assist with making updates on your site if you are not tech-savvy.

Because the frontend is built manually, any change you want to make has to be manually implemented as well.

If your business does not have a tech-savvy individual, it means you have to pay extra to hire a frontend developer that will perform daily maintenance on your website.

How WP Headless Works

Before implementing headless WordPress on your site, it is important to learn how the system works. Headless WordPress is similar to a decoupled architecture because both separate the frontend and the backend of a CMS.

However, in headless, you are not confined to a particular frontend technology like that of a decoupled CMS.

In a headless WordPress setup, the backend uses the traditional WordPress admin panel for adding and managing content on the CMS.

An API is then used to fetch data from your database. You can display the data from the API on your frontend website or any channel you want to publish your content.

A headless WordPress site is implemented using the WordPress REST API. The API is responsible for sending and retrieving data from the backend server to the frontend.

Fortunately, WordPress API makes the process easy for developers. To further simplify things, you can use WPGraphQL to implement wp headless on your site.

The WordPress API provides endpoints that you can use to access any aspect of your website, such as posts, pages, users, or custom post types.

How To Create a Headless WordPress Website

Now that you are familiar with the architecture behind the wp headless, we will show you how to use it in a WordPress installation in three easy steps.

Step One – Configuring a Custom Redirect

This step involves setting up a redirection from your WordPress homepage to the URL of your new frontend implementation.

You can set the redirection manually or using a WordPress plugin. Here, we will use the Headless Mode plugin to handle the redirection.

Headless Mode Plugin - Headless WordPress

This plugin lets you add a destination URL in the wp-config.php file, though you have to access your WordPress hosting server to do this. After adding the URL, the plugin will redirect all users trying to access your website to the URL you specify.

It will only allow requests from WP REST API or WPGraphQL. This enables you to get data from your backend through the API.

To get started, you need to install and activate the Headless Mode plugin on your WordPress website. Please check this guide for steps on how to install WordPress plugins.

After activating the plugin, you need to add a piece of code to your wp-config file.

For this, connect your site to an FTP client such as FileZilla. Learn how to do so here.

Once connected, on the right side, navigate to the directory containing your site files (usually public_html).


Here, right click on the wp-config.php file and select View/Edit. Select a text editor to open the file.

wp-config - Headless WordPress

Next, add the line of code below into the file.

define( 'HEADLESS_MODE_CLIENT_URL', 'https://mysite.com' );

Ensure you replace mysite.com with the actual frontend address. Save the changes, you will be prompted to override and re-upload the file.

Now anyone trying to access your website will be redirected to the new address you specified on the config file. This can be a static site for now. The backend remains untouched, meaning you can still perform administrative tasks such as adding posts or pages from your WordPress dashboard.

Step Two – Fetch and Display Content Using API

Now, you have successfully converted WordPress into a headless CMS. The next step is to retrieve content from the backend and then display it on any channel you intend to use.

You can use the WordPress REST API for this purpose. Other options such as WPGraphQL are available as well, however, we will stick with the WordPress API in this guide.

To start, simply enter your site address and then add ‘/wp-json’ to the address bar. The URL should look similar to the one below:


Replace mysite.com with the address of your WordPress blogs’ backend. Once you open the page, it will show your entire WordPress site in JSON format.

To access your posts, change the URL to the one below:


This will display an array containing all the posts on your WordPress site as JSON data. Each post data will have all the parameters such as the post_date, author, post_title, etc.

You can then display the response from the JSON API calls on your sites’ frontend using JavaScript frameworks such as ReactJS, or any other frontend technology.

Like we mentioned earlier, you need some technical knowledge to use the WordPress API. You can check our WordPress API guide for more details on how WP REST API works. The guide will show everything you need to know about the API.

Step Three – Building Your Website

This section involves building the website from scratch using your desired frontend framework. You can also use a static site generator such as Gatsby to build the frontend of your website.

Note that you need to be a proficient frontend developer to consume the data from the WordPress API. Otherwise, you would have to hire a frontend developer to spin up your web pages.

There are many frontend frameworks you can choose from such as React, Vue, Angular, or Gatsby. React is popular amongst them because of its lightweight design and speed.

When implementing your frontend, you will have to fetch data from the REST API and then render the data on your webpage.


React JS has a boiler template (create-react-app) that you can use to start developing your headless WordPress React website. You can check the official documentation for more information.

After developing the website, you can host it on the same server as your backend or host it on a separate server. When users visit your site, the custom-built frontend site will be displayed to them.

In the background, the API will fetch your content from the database and then the frontend takes care of displaying the content to your users.

Should You Use Headless WordPress?

There is no right or wrong answer to this question. Depending on the scenario, using WordPress as a headless CMS can be beneficial to your brand.

For instance, if you want to build a multichannel content publishing website, WP headless is a good solution. It makes the process easy because you can use one data source (REST API) for each of the applications.

Meanwhile, if you are creating a website for a client that is not tech-savvy, think carefully before using headless WordPress architecture. Using it will make managing the website difficult.

While headless wp seems to be the future, it may be overkill especially when you just need a simple site to manage your WordPress content.

So if you decide to use WordPress headless, we have shown you how to get started and how to apply the concept to your site. We hope you find this guide helpful.

 This post was written by Mesheal Fegor

Mesheal Fegor is a Web/WordPress Developer and technical writer. His WordPress help articles have been featured on Kinsta and other sites. Mesheal holds a master's degree in computer science. His writing focuses on technical WordPress issues, ranging from core WordPress problems, to issues with WooCommerce, and more.

Last edited by: FixRunner Team