WordPress is powerful — currently, over 40% of all websites use it to some extent, and most of these use the standard WordPress setup you’re likely familiar with. If you’re not, here’s our guide to WordPress websites.

But, even WordPress has its limitations. Though it offers a lot of flexibility by way of themes and plugins, website owners are limited to these tools if they want to customize their site. What if, for example, you wanted to design the visuals of your website outside the constraints of a theme?

If that sounds like you, consider a headless WordPress setup. With headless WordPress, your website’s content database is decoupled from your website’s display, providing more flexibility, easier multi-channel distribution, and faster performance.

In this guide, I’ll introduce you to the concept of headless WordPress: what it means for a CMS to be headless, the benefits of a headless CMS configuration, and why (or why not) you should change how your site is set up.

Grow Your Business With HubSpot's Tools for WordPress Websites

And yes, I know “headless” sounds morbid, but I promise it’s just an analogy. Let’s dive in.

What is headless WordPress?

To understand what makes a headless WordPress configuration different from traditional WordPress, we first need to talk about headless content management systems in general. For a more detailed explanation, you can read our intro guide to headless CMSs. For now, though, here’s what you need to know:

Most CMSs you’ve likely worked with are meant to handle both the front end of the website — the interface that visitors interact with, such as a web page — and the back end of the website — the files stored on servers, including scripts and a content database. The back end is where you create, organize, and manage the content before publishing it to the front end.

We can refer to this setup as a “coupled” CMS architecture, since the front-end editing tools and back-end management tools are paired in the same system. A coupled architecture lets website owners manage their entire website from inside one intuitive program (such as WordPress), making this setup popular with beginners.

A headless CMS works differently: It removes the front-end tools, leaving only the back-end content management tools. Essentially, you’re separating the “head” (the front end) of your website from the rest of its “body” (the back end).

Headless CMSs still allow you to upload, create, edit, and organize content. But, instead of pushing content directly to the front end, a headless CMS makes its resources available to a separate front-end solution through a REST API. It doesn’t concern itself at all with how the content looks to visitors.

wordpress headless cms vs traditional cms diagram

Here’s where headless WordPress comes in: The WordPress as you and I (and most people) know it uses a coupled architecture. You manage your website’s assets in the dashboard and control its appearance through themes and plugins.

But, by eliminating themes and instead sharing content via the WordPress REST API, any WordPress installation can be made headless. In a headless WordPress configuration, the content management tools are still available, but front-end features like themes and the block editor are not. Another front-end application handles how your WordPress website actually looks.

A headless setup isn’t the best solution for all WordPress users. However, there are times when this configuration is ideal. Next, let’s discuss why a business might want to try headless WordPress.

Benefits of Headless WordPress

Why would anyone forgo the convenience of traditional WordPress for headless? In some cases, a headless setup may be better suited for a business website than a typical WordPress installation. Here are some key reasons why:

Front-End Flexibility

WordPress allows you to do a lot with the front end, with its huge selection of customizable themes and plugins. Still, not everyone may want to control their website front end this way — you’re still constrained to WordPress.

With a headless CMS, you can keep the “content management” part of the WordPress CMS that you know and love, and outsource your front end to virtually any other software you want, as long as that software can make requests to the WordPress API.

This is especially beneficial for front-end developers who want to work inside another application, use different coding languages than what WordPress uses, and/or add a front-end framework like React to make their jobs easier.

WordPress is built mostly of PHP and JavaScript, but headless WordPress lets developers retrieve site content, package it however they want without WordPress’s limitations, and stick it on a web page for your audience to see. Meanwhile, your content team can continue to work in WordPress without worrying about what tools these developers are using.

Additionally, what if you need to change your front-end system? Or, what if you want to redesign your site, or build it back up from scratch? Headless WordPress arguably makes these all easier, since your content is decoupled from the front-end. You can alter your website’s face as much as you want, but the content remains unchanged.

Multichannel Publishing

When starting with WordPress, you’ll be using it for your standard desktop and mobile websites, and that might be all you need it for. However, some scaling businesses may want to send their content to additional interfaces, like mobile apps, social media sites, smart devices, and virtual assistants like Alexa.

If this is the case, a headless CMS can serve as a centralized source for multiple publishing channels. When you make a change to some content in the CMS, this change is automatically reflected across every device connected to it.

Imagine trying to do this with a traditional CMS. You’d need to reformat your content for every interface — that’s simply not scalable.

Improved Performance

Traditional WordPress renders web pages dynamically. This means that, instead of storing static HTML pages to send to users when requested, the hosting server constructs an HTML page each time a request comes in. In simple terms, WordPress uses PHP to fetch all the necessary resources from the database, assemble them into a page, then send this page to a user.

As you might guess, this process isn’t always the fastest, and slow page loads can hurt the user experience and reduce conversions. By leaving the front-end delivery up to a separate application, you can potentially speed up your site. For example, you can fetch content from WordPress and assemble it into static HTML pages, then ship the static pages to clients upon request.

a diagram showing static vs dynamic wordpress websites

Image Source

While there are many simpler things you can do to improve performance in a standard WordPress installation, faster speeds are another compelling reason why some businesses may opt for headless WordPress.

Improved Security

Again, there are things you can do to protect your WordPress site without going headless, but the security benefit is one more bonus of a headless setup.

If your front-end is separated from your content, it will be much more difficult to locate and access your content directly through your website, as long as your back-end server is sufficiently hidden.

Drawbacks of Headless WordPress

Before you start messing with your WordPress back end in an attempt to go headless, keep in mind that this solution isn’t ideal for the majority of WordPress users, and the benefits may outweigh the drawbacks. Namely, headless WordPress requires a lot of effort, and skilled effort at that.

A big draw of the WordPress CMS is the code-free experience. With headless WordPress, that promise pretty much goes out the window. You’ll need to either already be very comfortable with front-end development languages like JavaScript, or hire someone who is. For example, headless WordPress gets rid of the visual editor, so there’s no more dragging-and-dropping to build your interface.

On top of the necessary skills, running a headless WordPress website is a significant time investment — you now have two systems to look after instead of just one. If you’re not publishing content at a high rate, then the time, cost, and energy needed to run such a website aren’t worth the switch. That’s why you tend to see headless configurations adopted more often by larger companies with enough resources to handle the job and enough content and channels to justify the investment.

How to Set up a Headless WordPress Website

If you’ve weighed the pros and cons of headless WordPress and decided it’s worth pursuing, there are several ways to go about it. Your method will vary based on your technical expertise and resources, preferred languages and frameworks, and your preferred WordPress host that can offer headless hosting.

Regardless of your method you should be comfortable with front-end languages (including JavaScript) and with the WordPress REST API. No matter how you slice it, you’ll be coding the front-end yourself or paying someone to do it for you.

We can break down the different approaches to headless WordPress into two general categories: plugins and coding it yourself. Let’s briefly discuss each method next.

Use a plugin.

WordPress plugins typically act as workarounds to writing code yourself. This unfortunately is not the case for headless WordPress plugins, which still require you to be well-versed in relevant programming languages and API concepts in order to build your front-end and make requests to the API. However, there are a couple notable (and free) plugins available that can make your life easier.

The main plugin we want to highlight is WPGraphQL, which lets developers turn their WordPress installation into a GraphQL API. What this means is that developers can create their own data schemas that any front-end client may use to retrieve data from your headless CMS. You may prefer a GraphQL-powered API over the WordPress REST API if you want to write your own data schemas and write runtime code that dictates how your API handles specific requests.

download page for the headless wordpress plugin WPGraphQL

Image Source

If you’re interested in headless ecommerce, CoCart is another WordPress plugin to consider. CoCart takes your WooCommerce store and puts a headless API on top of it, allowing front-end clients to request store resources like product and cart contents. This plugin can be highly useful if you want to launch a store on multiple platforms (e.g., a website and a mobile app) and manage your content from one WordPress/WooCommerce back end.

download page for the headless wordpress plugin cocart

Image Source

Lastly, once you’ve set up the front end of your headless site, you can use the Headless Mode plugin to send anyone trying to access your old WordPress site to your new front-end address. This plugin is very simple and ensures returning visitors won’t be confused trying to access your old site after you’ve changed URLs.

Code it yourself.

While plugins make implementing an API easier, you can’t beat the DIY coding approach if you want flexibility. There are many tutorials online that explain in-depth and step-by-step how to implement a headless configuration in your copy of WordPress.

For those brand new to headless WordPress, the best step-by-step guide to working with the WordPress REST API is this one from Smashing Magazine that walks through each step of the process with code snippets that you can use yourself.

Rather than building the front end of your website from scratch, we’d also recommend learning a front-end framework that handles much of the heavy lifting for you. Gatsby is one such framework that’s notable for its compatibility with WordPress. With it, you can manage your content through WordPress. Then, deploy your website through Gatsby’s cloud service while enjoying the performance boost that Gatsby gives you.

For more info on the improvements that Gatsby offers, check out this video from the developers:

If you haven't already, we’d also recommend looking into react React, a JavaScript library owned by Meta for building front ends and reusing components for better performance. To connect your WordPress backend with a React-powered front-end site, try the free and open-source framework Frontity, which makes it easier to specifically build WordPress-React sites.

Need a more flexible WordPress? Try going headless.

While headless WordPress will not end traditional WordPress as we know it, it’s a feasible option for businesses large enough to support the cost of implementation and maintenance. It might seem like more work at first to get started, but a headless approach could save you tons of time down the road and grant you more front-end flexibility than WordPress ever could out-of-the-box.

Editor's note: This post was originally published in November 2021 and has been updated for comprehensiveness.Use HubSpot tools on your WordPress website and connect the two platforms  without dealing with code. Click here to learn more.

 Use HubSpot tools on your WordPress website and connect the two platforms  without dealing with code. Click here to learn more.

Originally published Apr 20, 2022 7:00:00 AM, updated April 20 2022

Topics:

WordPress Website