Use React on a custom WordPress settings page

Published: December 5, 2022 – Leave a comment

Using React inside the block editor is pretty straight forward since all requirements are already met. But what if you want to use React on a custom page? In my case, I wanted to use React on a custom settings page. Since I couldn’t find any information of how to achieve that, I looked into it deeper.

Setup settings page

If you’ve already used React in other projects, you will notice that the approach is very similar. First, you need to have a root element to render your React app into. For a custom settings page, it could look like this:

add_action( 'admin_menu', function() {
	add_submenu_page(
		'options-general.php',
		__( 'My Settings', 'textdomain' ),
		__( 'My Settings', 'textdomain' ),
		'manage_options',
		'my-settings',
		function() {
			return '<div id="react-app"></div>';
		}
	);
} );
Code language: PHP (php)

This creates a submenu item to the “Settings” menu item and just places a <div id="react-app"></div> as content.

Build assets

Now we need to make sure our assets will be enqueued on this page. I recommend using the npm package @wordpress/scripts to build your assets since this will automatically build all dependencies. Install it using the command npm -i @wordpress/scripts --save in your command line. Afterwards, create a JavaScript file in src/index.js of your project folder.

To start building the asset, run the command wp-scripts start. It will now create a build folder with an index.js as well as an index.asset.php. The latter contains all dependencies.

Enqueue assets

Now it’s time to enqueue the assets. This is pretty similar to enqueue other assets in plugins and themes:

add_action( 'admin_enqueue_scripts', function() {
	if ( get_current_screen()->id !== 'appearance_page_my-settings' ) {
		return;
	}
	
	$asset_file = include_once plugin_dir_path( __FILE__ ) . 'build/index.asset.php';
	
	wp_enqueue_script( 'my-handle', plugin_dir_url( __FILE__ ) . 'build/index.js', $asset_file['dependencies'], $asset_file['version'], true );
	wp_set_script_translations( 'my-handle', 'textdomain', plugin_dir_path( __FILE__ ) . 'languages' );
	wp_enqueue_style( 'my-handle', plugin_dir_url( __FILE__ ) . 'build/style-index.css', [], $asset_file['version'] );
} );
Code language: PHP (php)

Since I use the code only in the admin, I use the hook admin_enqueue_scripts. If you want to use it in the frontend, use the hook wp_enqueue_scripts. Also, I limit the execution of this function to my settings page via get_current_screen. This function doesn’t work in the frontend, be aware of that.

As you can see, I use the asset file to output its data for the wp_enqueue_script function. This automatically enqueues all necessary core scripts to use React on your custom page. And I also setup translations for the React code as well as enqueuing a style.

Using React

Last but not least, we need to render our custom code to the element we added to our custom settings page:

import { render } from '@wordpress/element';
import './style.scss';

render(
	<p>Hello, World</p>,
	document.getElementById( 'react-app' )
);
Code language: JavaScript (javascript)

This will output a paragraph with the content “Hello, World”.

Bonus: Using snackbar

During development I noticed that the snackbar functionality didn’t work on my custom settings page. After some investigation through the source code I could find the reason for that: The snackbar is added via EditorSnackbars from @wordpress/editor. Giving the example above, I could adjust it like this to get the snackbar working:

import { EditorSnackbars } from '@wordpress/editor';
import { render } from '@wordpress/element';
import './style.scss';

render(
	<>
		<p>Hello, World</p>

		<EditorSnackbars />
	</>,
	document.getElementById( 'react-app' )
);
Code language: JavaScript (javascript)