Skip to main content

Build Your First Template

In an integrated theme, WordPress resolves the URL and ReactWP maps the resulting template name to a React component. This guide creates that component and connects it to a page.

Create the Component​

Create src/themes/reactwp/js/templates/About.jsx:

import '../../scss/templates/about.scss';

const About = ({ route, site, navigation }) => {
  return (
    <section id="about">
      <h1>{route.pageName}</h1>
      <div className="about__content">{route.data.introduction}</div>
    </section>
  );
};

export default About;

Every registered template receives the same top-level props:

PropContains
routeCurrent route identity, template, title, SEO, data, media groups, and render metadata
siteShared site identity, URLs, language, and site-level values
themeActive theme name, slug, and version
systemRuntime URLs, REST nonce when available, cache generation, and infrastructure values
navigationNormalized WordPress menus keyed by location
currentUserIntegrated WordPress identity; always includes authenticated

Project-specific ACF fields for the current page are available through route.data.

Read the Current Language​

Use route.lang for the language of the route currently being rendered. It changes with the normalized route payload during client navigation. Use site.language as the initial bootstrap fallback, and site.locale when the complete WordPress locale such as fr_CA is required.

const About = ({ route, site }) => {
  const language = route.lang || site.language || 'en';
  const locale = site.locale || 'en_US';

  return (
    <section lang={language} data-locale={locale}>
      <h1>{route.pageName}</h1>
    </section>
  );
};

Code outside a template can read the initial bootstrap language from the runtime:

import { runtime } from '../inc/Runtime';

const initialLanguage = runtime.site.language;

runtime.site.language is not a reactive replacement for route.lang: persistent shell code that must follow language-changing navigation should receive the current route from App.jsx instead of retaining only the initial bootstrap value.

Register the Template​

Open:

src/themes/reactwp/js/inc/config/configureTemplateRegistry.js

Register the component with the exact name WordPress will use:

import { registerTemplate } from '../TemplateRegistry';

export const configureTemplateRegistry = () => {
  registerTemplate('About', {
    loader: () => import('../../templates/About'),
    render: 'client'
  });
};

The dynamic import creates a lazy template chunk. ReactWP preloads that chunk before revealing the route.

The shorter client-only form is also supported:

registerTemplate('About', () => import('../../templates/About'));

Assign It in WordPress​

In the WordPress admin:

  1. Open Site settings and make sure the page's post type is enabled under React Template Post Types.
  2. Edit the page that should use the component.
  3. Enter About in the React Template field.
  4. Update the page.

The value is case-sensitive and must match the registry name. When the field is empty, ReactWP uses Default.

Add Page Fields​

Create an ACF field group for the page or its template. ReactWP removes internal route fields and exposes the remaining values through route.data.

For an ACF field named introduction, read:

const introduction = route.data.introduction || '';

Use WordPress escaping and React rendering patterns that match the field type. The Components guide documents helpers such as Contents, RichText, Image, Video, and AppLink.

Add Styles​

Create the imported stylesheet at:

src/themes/reactwp/scss/templates/about.scss

SCSS imported by a template is extracted into its own CSS chunk. In static and server modes, ReactWP can enqueue that template CSS before the initial paint.

Choose a Render Mode​

Client rendering works without any extra configuration. Public pages can move to static HTML without changing their component:

registerTemplate('About', {
  loader: () => import('../../templates/About'),
  render: 'static'
});

Request-dependent pages can use render: 'server' when the optional Node render service is available in production.

Continue with Client, Static, and Server Rendering before enabling static generation or SSR.

Next Steps​