Headless WordPress

Learn what headless WordPress means, how it differs from other ways of using WordPress, and how you can use headless WordPress with Gatsby.

What is Headless WordPress?

Headless WordPress is the practice of using WordPress as a headless CMS for your JAMstack site. Headless WordPress takes advantage of the WordPress REST API to separate its content from the frontend that displays it.

Note: WordPress has two products: an open source, self-hosted package that you can download from WordPress.org; and a hosted service, WordPress.com. This article applies to both.

Most WordPress installations use themes, which are a collection of template files, to display content. A WordPress template file mixes HTML with PHP template tags, and controls the layout of a particular page or page type — e.g. single.php for individual blog posts; home.php for the home page. The downside of this template-based system is that the content is only available as HTML, using the document structure defined by each template.

The WordPress REST API, on the other hand, returns JSON instead of HTML. Using a content API gives you more flexibility around what kind of frontend you use: vanilla JavaScript, a native mobile application, your Gatsby site, or all of the above.

Gatsby supports WordPress as a content source with the gatsby-source-wordpress plugin. As with Gatsby, you can install the gatsby-source-wordpress plugin using npm:

The gatsby-source-wordpress plugin works with self-hosted WordPress sites, and those hosted by WordPress.com. Be aware, however, that the WordPress.com API supports a smaller set of features than that of self-hosted WordPress sites. It’s also compatible with the Advanced Custom Fields plugin.

Headless WordPress lets your content team use an interface they’re familiar with, while giving you the flexibility to use any frontend you’d like.

Learn More

Edit this page on GitHub