This guide shows you how to embed a standalone React application into a WordPress site, whether it’s a plugin, theme, or page builder. You’ll learn the modern approach using a build tool and the WP REST API, so your React app runs smoothly alongside WordPress without conflicts. By the end, you’ll have a working integration that loads your React component on any page or post.
What You’ll Need
- A WordPress site (self-hosted or local) with admin access.
- Node.js and npm installed on your computer (for building the React app).
- Basic familiarity with React and the command line.
- FTP or file manager access to your WordPress installation (or use the theme editor if you prefer).
- Optionally, a code editor like VS Code.
Step-by-Step
- Create a new React app (if you don’t have one). Open your terminal and run:
npx create-react-app my-widgetThis sets up a standard React project. If you already have an app, skip to step 2.
- Build your React component as you normally would. For this example, we’ll create a simple counter component in
src/App.jsthat you want to embed. Make sure it’s self-contained and doesn’t rely on routing or server-side rendering. - Configure the build output. By default, Create React App outputs files with hashed names and assumes the app is served from the root. To make it work inside WordPress, edit
package.jsonand add:"homepage": "."Then, in
src/index.js, change the rendering to target a specific element that WordPress will provide. For example:import React from 'react'; import ReactDOM from 'react-dom'; import App from './App'; const rootElement = document.getElementById('my-react-app'); if (rootElement) { ReactDOM.render(, rootElement); } This prevents React from taking over the whole page.
- Build the app. Run
npm run build. This creates abuildfolder with static files:index.html,static/js/main.js, andstatic/css/main.css(names may include hashes). - Upload the built files to WordPress. Use FTP or your hosting file manager to upload the contents of the
buildfolder to a directory inside your active theme, e.g.,/wp-content/themes/your-theme/react-app/. Alternatively, you can upload to the root or a custom folder. - Enqueue the scripts and styles in WordPress. Open your theme’s
functions.phpfile (via Appearance > Theme Editor or a code editor) and add the following code to load the React files only when needed:function load_react_app() { if ( is_page('my-react-page') ) { // Replace with your page slug or condition wp_enqueue_script('react-app-js', get_template_directory_uri() . '/react-app/static/js/main.js', array(), null, true); wp_enqueue_style('react-app-css', get_template_directory_uri() . '/react-app/static/css/main.css'); } } add_action('wp_enqueue_scripts', 'load_react_app');Adjust the file paths to match where you uploaded the files. The
is_page()condition ensures the scripts only load on the page where you want the app. - Add a container element to your page. Create a new page in WordPress (or edit an existing one). In the page content, switch to the HTML/Code editor and add:
<div id="my-react-app"></div>This is the element that React will mount into. Save the page.
- Test your page. Visit the page in your browser. You should see your React app rendered. If not, check the browser console for errors.
Common Mistakes
- Forgetting to set the homepage in
package.json– this causes broken asset paths (404 errors for JS/CSS). - Using
ReactDOM.renderon the document root – this will overwrite the entire WordPress page. Always target a specific div. - Loading scripts on every page – this slows down your whole site. Use conditional loading as shown.
- Not clearing the browser cache – after uploading new files, hard refresh (Ctrl+Shift+R) to see changes.
- Mixing jQuery and React – avoid using jQuery to manipulate the same DOM elements that React controls; it can cause unexpected behavior.
Tips
- Use a custom shortcode for more flexibility. Instead of hardcoding a page slug, create a shortcode that outputs the container div and enqueues the scripts. This way you can embed the app anywhere.
- Consider a plugin for a more modular approach. You can create a simple WordPress plugin that handles the enqueueing and shortcode, making it theme-independent.
- Use the WP REST API to pass data from WordPress to React. For example, fetch posts or settings via
fetch('/wp-json/wp/v2/posts')and use them in your component. - Minify and optimize your React build for production. The default build is already minified, but you can further reduce size with code splitting.
- Test in a staging environment before deploying to production, especially if you’re modifying theme files.
Troubleshooting
- White screen or blank page: Check the browser console (F12) for JavaScript errors. Common causes: wrong file path, missing element ID, or React not loading. Verify that the script URL is correct and the file exists.
- Styles not loading: Make sure the CSS file is enqueued and the path is correct. Also, ensure your theme’s CSS doesn’t override your React styles.
- App loads but appears unstyled: This often happens if the CSS file is not enqueued or is loaded in the wrong order. Use
wp_enqueue_stylewith a dependency on the theme’s main style if needed. - React app appears but then disappears: This can happen if WordPress or another script re-renders the page. Make sure you’re not using any AJAX that replaces the container’s innerHTML.
- Script loads but nothing renders: Double-check that the element ID in your HTML matches the one in your JavaScript. Also, ensure that the script is loaded after the DOM is ready (the
trueparameter inwp_enqueue_scriptloads it in the footer, which is fine). - 404 error for main.js: Check the file path. If you uploaded to a subfolder, make sure the URL in
get_template_directory_uri()includes that subfolder correctly.
Frequently Asked Questions
Can I embed a React app without a build step?
Yes, you can use React via a CDN (like unpkg) and write JSX with Babel standalone, but this is not recommended for production due to performance and maintainability. The build step is best practice.
Will this work with any WordPress theme?
Yes, as long as you enqueue the scripts and styles correctly. The method uses standard WordPress hooks, so it works with most themes. However, some themes may have CSS conflicts; you may need to adjust your component’s styles.
Can I use React Router or other libraries?
Yes, you can include any React library in your app. However, if you use React Router, make sure to use a BrowserRouter with a basename that matches the WordPress page URL, or use HashRouter to avoid server configuration issues.
How do I pass data from WordPress to my React app?
You can use wp_localize_script() to pass PHP data as a JavaScript object. For example, wp_localize_script('react-app-js', 'wpData', array('post_id' => get_the_ID())); then access window.wpData in your React app.
Is it better to use a plugin or theme integration?
It depends. A plugin is more portable and won’t break if you change themes. A theme integration is simpler for a one-off project. For most cases, a plugin is recommended.
Can I embed multiple React apps on the same page?
Yes, you can have multiple containers with different IDs and render different components into each. Just make sure to load the scripts once and use unique IDs.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Samsung Smart Speaker Rollable Display: Facts
- HP 9730e: Wide Prints, Not A3 Scans
- What 8888 Does When You Use It as DNS Server
- Credential Manager: Seamless Sign-In Explained
- API Governance for Public Data: What Growing Portfolios Need
- Enterprise AI Hidden Cost: Data Architecture ROI