Creating Checklist Component for Gutenberg Sidebars

October 10, 2022

I already have a couple of tutorials about working with metadata in Gutenberg, so you can find a complete guide to it and a separate tutorial about image fields. Now let’s continue to dive into it and discuss types of fields that consist of multiple input elements.

We are not going to dive straight into the repeater fields (let’s do it later) and discuss something more simple, a checklist field for example.

That’s how it is going to look like:

checklist field in Gutenberg sidebar — If you’re interested in how to create an image field, there is a separate tutorial about that.

Right now I am going to show you how to create a React component for a checklist, there is going to be a lot of JSX code, so if you’re seeking for a more simple PHP solution, please go straight into the last chapter of this tutorial.

Let’s begin with register_meta() type of array

You already should know that without registering a meta key in REST API it is not going to work in Gutenberg. In order to do so we are going to use register_meta() function.

But there is one thing we have to discuss before using it. Actually we need to decide what type of data will be stored as a meta value. For multiple checkboxes my suggestion is to store an array of values like [ 'value1', 'value2', ... ]. The values themselves could be both of integer or string types. We have to do two things:

Specify type parameter with array value.
In order to prevent the error notice Function register_meta was called incorrectly. When registering an “array” meta type to show in the REST API, you must specify the schema for each array item in “show_in_rest.schema.items”, we must have a special value for show_in_rest parameter. In other words let’s just let the function know what is inside our array.

The final code is below:

register_meta(
	'post', 
	'misha_checklist', 
	array(
		'type' => 'array',
		'single' => true,
		'show_in_rest' => array(
			'schema' => array( 
				'type'  => 'array', 
				'items' => array( 
					'type' => 'string' 
				)
			)
		)
	)
);

Creating a Gutenberg WordPress Component for a Checklist

The Gutenberg components we are going to use here:

CheckboxControl – a checkbox field component itself.
BaseControl – it is just a wrapper for checkboxes, allows to display a label and description
useSelect – we are going to use it instead of withSelect in order to get meta values from the database.
useDispatch – we need it to update the meta values in the database, previously we used withDispatch but you can use any of them.

const { BaseControl, CheckboxControl } = window.wp.components
const { useSelect, useDispatch } = window.wp.data

const RudrChecklistControl = ( props ) => {
	
	// get the meta value
	let { checklistValues } = useSelect( select => {
		const metaValue = select( 'core/editor' ).getEditedPostAttribute( 'meta' )[props.metaKey];
		return {
			checklistValues: metaValue,
		}
	})

	// a function that updates the meta value
	const { editPost } = useDispatch( 'core/editor', [ checklistValues ] )

	return (
		<BaseControl label={ props.label }>
			{ props.options.map((item, index) =>
				<CheckboxControl
					label={ item.label }
					checked={ checklistValues.includes( item.value ) ? true : false }
					onChange={ ( checked ) => {
						// remove current element anyway
						checklistValues = checklistValues.filter( value => value !== item.value )
						// put it back if the checkbox is checked (maybe you know a simpler way? tell me in comments)
						if( checked ) {
							checklistValues.push( item.value );
						}
						editPost( { meta: { [props.metaKey] : checklistValues } } )
					} }
				/>
			) }
		</BaseControl>
	)

}

export default RudrChecklistControl

Once the component is ready, you can use it like this in plugin sidebars:

<RudrChecklistControl
	metaKey="misha_checklist" 
	label="Checklist" 
	options={[
		{ 'label' : 'Coffee', value : 'coffee' },
		{ 'label' : 'Avocado', value : 'avo' },
		{ 'label' : 'Eggs', value : 'egg' },
		{ 'label' : 'Bread', value : 'bread' }
	]}
/>

Ta-da!

Doing the Same in PHP

In case JSX code seems overwhelming, you can still use a PHP way. Just two steps:

Install and activate my Simple Fields plugin on your website.
Copy and paste the following code into your current theme functions.php file or to a custom plugin:

add_filter( 'simple_register_sidebars', 'misha_gutenberg_sidebars' );

function misha_gutenberg_sidebars( $sidebars ) {

	$sidebars[] = array(
		'id' => 'misha-test',
		'post_type' => 'page',
		'name' => 'Misha Test',
		'icon' => 'food',
		'fields' => array(
			array(
				'id' => 'mishachecklistfield',
				'type' => 'checklist',
				'label' => 'Checklist',
				'options' => array(
					'coffee' => 'Coffee',
					'avo' => 'Avocado',
					'egg' => 'Eggs',
					'bread' => 'Bread',
				),
			),
		)
	);

	return $sidebars;

}

And we have a completely ready-to-use Gutenberg plugin sidebar, even without register_meta() step.