React single-page WordPress REST API theme tutorial

Uh-oh, such a buzz-wordy title. I know, I know. But it’s true — I’m going to publish a series of articles on building a simple single-page WordPress theme powered by React, WP REST API, and other bleeding-edge front-end technologies. The tutorial will be focused primarily on the JavaScript things, pushing design, accessibility and flexibility sideways. It will contain a lot of new technologies and things so don’t worry about not learning something new.

Tutorial navigation

  1. React single-page WordPress REST API theme tutorial (current)
  2. React WP theme: structure, Node packages and Webpack
  3. React WP theme: Smart vs Dumb components + React Router
  4. React WP theme: Creating dumb components
  5. .
    . to be written

Final result

I don’t have the blog coded up yet so there is no online demo. It will be a single-page theme based on Bootstrap blog design because I don’t want to spend much time in the design space and concentrate on the JS part instead. It’s main navigation will be composed of static menu items: home, about, articles. On the home page, there will be last 10 articles listed, without pagination. The other pages (except ‘Articles’) will be just simple pages matching their counterparts in the WordPress admin. The blog will not be much dynamic, no sidebars, but this is because I want to keep it simple. We might do that stuff later.

You can watch the progress on my “Lexi” GitHub repo.

Strong and weak parts

The blog will be single-page so it will be super-fast. Content will load on the background with Ajax requests by using WP REST API on the server-side.

The weakest part is that it won’t be dynamic and also it will not be universal (isomorphic). We might go around this problem by precomposing our application but for now, we won’t render anything on the server and everything on the client.

More on the technologies used in the later part of the article.

What you’ll learn

A lot, especially if coming from the PHP/jQuery world. We’ll jump on the React/Flux train and see all the best there. After finishing the tutorial, you’ll be able to build your own WordPress theme or plugin using these technologies. And anyways, it’s always good to learn new skills and technologies — they might catch up in a few years and you’ll be among the first ones to know how to use them.

A bit about technologies/tools we’ll be using


JavaScript library for building user interfaces the easy way. We define them declaratively with an HTML-like language (JSX), supply them with data and React will do the rest — and fast, too. I’ve written more about React in the other article.


JavaScript library for managing the state (or the data) of our WordPress theme. It loosely follows the Facebook’s Flux architecture of single-page applications but differ in many aspects. For example, instead of having multiple stores, in Redux there is only a single store. We create this store from reducers, which manipulate the data. Redux is fully Universal.


Unlike AngularJS, React doesn’t have routing built-in. If we were to program it ourselves, we would have to manage page transitions, remember current URL both in memory and in the URL field (with HTML5 history API) and much more. Fortunately, some good folks have created React-Router, a full-featured routing library for React-based web apps.


If you know Grunt or Gulp, Webpack is their (r)evolution. The main difference is that Webpack is much faster than any of them. It splits the modules into chunks, compiling only those which have been changed. It means that when you style your site in Sass and have many dependencies (such as Bootstrap), Webpack will compile everything on the first run (slow) but on the next runs it will only compile those files (or part of files) which have changed. Really fast.

What is more, Webpack supports so-called “loaders”. They are Webpack plugins which tell it how to compile/preprocess files. This way, if Webpack doesn’t support your favorite language, just write a new loader or pitch it to some of these folks. But in reality, most of the loaders are already programmed (Sass, JSX, etc).

ES6 or ECMAScript 2015

ES6 or ECMAScript 2015 is the long-awaited iteration of JavaScript language, bringing plenty of new features and cool syntactic sugars, including:

  • module management (importing/exporting)
  • class syntax with inheritance, constructors, methods, and properties
  • the let keyword for creating new variables with block visibility (better than global var)
  • arrow functions with lexical this (don’t have to do the `var that = this` trick anymore)
  • and much more

While all of this is nice, most of ES6 is not yet widely supported among browsers. That’s where BabelJS comes into play. It’s a JavaScript compiler which translates ES6 JS into standard ES5 one. Babel even supports React and JSX out of the box! The best thing is that Babel can be used with Webpack as a loader, making the compilation pretty fast.


Much has been written about WP REST API both on my blog and on the web so I’m not going to repeat myself here.

I have to complain a bit here. When I used WP REST API for the first time, I was really excited about its possibilities. However, when I started to work on this single-page WP theme, I found out that it lacks many important features. It has no API endpoints for these things:

  • site menu navigations (e.g., no way to get the items in the main menu)
  • site permalink structure (what’s the link to an article? /%year%/%month% or vice versa or what)
  • widgets
  • and some other things I’ve forgotten since

Without the above features, you can’t really build a standard, dynamic single-page WP theme.

On the other hand, WP REST API is open source so instead of complaining, I should be contributing. Pity me!


Bootstrap is the most popular front-end framework for making nice and UX-friendly web pages. They are just releasing the 4th version so I’m going to jump right into it. This project is on a cutting-edge of web technologies.


I think that we are on a brink of a revolution in the web, especially in the WordPress ecosystem. As people get used to the awesome UX of single page applications (like Facebook), they will demand similar experience of all the websites. You might say that SPAs are not SEO-friendly and not good for sites with a lot of content, but I have to disagree. Google already crawls SPAs, we just need to help it a little by precomposing or server-rendering it.

What is more, I think now is the best time to start learning and using WP REST API in combination with React/AngularJS. Not many people are using them yet, but they are becoming pretty mature technologies. And when WordPress will finally include WP REST API in the Core, you’ll be ready.

Useful resources and inspiration

In addition to the links provided throughout the article, here are some more interesting ones:

React/AngularJS WP Themes:

Universal (isomorphic) WP theme how to:

Oh, by the way, I’m calling the theme “Lexi”, which is the nickname of my girlfriend Alexandra. 🙂

Join the Conversation


    1. Hello Antifaith,

      definitely go for it. It’s a very good learning experience.

      I don’t have any updates, sorry. If you don’t know how to start, look at my theme’s repo:

      Automattic’s Picard is also a nice starting point: What I like the most about it is how they try to solve the server-side rendering issue:

      I looked into Redux examples when doing my theme: You can find a lot of goodies there.

      Good luck with your theme.


  1. Have you tried using nav_menu_item as the post_type? The docs for V1, under retrieve posts says

    type – Post type of the post: post, page, link, nav_menu_item, or a any custom registered type. Default is post. (string) optional

    So I think you could try something like wp.posts().type( nav_menu_item )


  2. Very cool, looking forward to getting my hands dirty with this. May i ask why Redux instead of Flux, and would it be difficult to fork and replace Redux with Flux?


    1. Hey there, thanks!

      Flux is just a name for an architecture for building client-side apps ( Redux is a specific implementation of this architecture (well, not exactly, see their differences here:

      There are many great Flux implementations too. I chose Redux mainly because I wanted to learn it. During the time I was thinking about doing such a project, Redux was very hot, so why not?

      It shouldn’t be difficult to replace Redux with Flux. Fork Lexi and give it a try. 🙂


  3. Hi iam waiting for the rest please write them … Iam very curious to see this in my production ….


  4. I don’t know where you are in this project now. Hope it goes well!

    I’m planning to do so for my wp website too. Well in fact I thought about leaving WordPress, as I’m the only user, and publish markdown files that would be automatically added as articles… But I’d like to have some comments, and I hate Disqus, so… Yeah, I’ll probably stick with WordPress.

    I’m hesitating between React and VueJS though… Seems like VueJS has a better separating of markup / style / js, but i like the “no-dom-manipulation” thing of react.

    Anyway, your github will be really helpful to me. Thanks!


  5. Do you know if it’s possible to combine a react single page app with a wo spread home page and.have different views for users who are logged in (taking them somewhere different) versus users who are logged out? Looking everywhere for more info on this and how to go
    about it.


Leave a comment

Leave a Reply to Simon Hampton Cancel reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: