Show and Tell: the WordPress FormTokenField Component

The FormTokenField component is useful for outputting tags, hashtags, users, or any token format.

For QuotesDLX, I used the component in both the block editor and the admin area. I use it for hashtag output, as you can see in the example below.

Pin itWebShare

FormTokenField in the admin panelOpens in a new window

For my React screen, I needed to use the FormTokenField component to display and provide an interface for inputting hashtags.

First was including it via @wordpress/componentsOpens in a new window.

Pin itWebShare

I then use React Hook FormOpens in a new window to control the saving/outputting using their handy controllerOpens in a new window.

<Controller
	name="hashtags"
	control={ control }
	render={ ( { field: { onChange, value } } ) => (
		<FormTokenField
			value={ value }
			placeholder={ __(
				'Enter hashtags separated by commas.',
				'quotes-dlx'
			) }
			className="quotes-dlx-hashtag-fields"
			tokenizeOnSpace={ true }
			label={ __( 'Hashtags', 'quotes-dlx' ) }
			onChange={ ( tokens ) => {
				const filteredTokens = [];
				tokens.forEach( function( item, index ) {
					const replacement = item.replace( '#', '' ); // Strip hashtag symbol.
					const hashtag = twttr.txt.extractHashtags(
						'#' + replacement
					); // Add it back in for extraction.
					// Check if array contains anything.
					if ( typeof hashtag[ 0 ] !== 'undefined' ) {
						filteredTokens.push( hashtag[ 0 ] );
					}
				} );
				onChange( filteredTokens );
			} }
		/>
	) }
/>Code language: JavaScript (javascript)

There are some notable attributes, so let’s go over each one I use.

The value attributeOpens in a new window

The value attribute accepts an array of tokens. An example of this array can be found in the FormTokenField documentation:

const continents = [
    'Africa',
    'America',
    'Antarctica',
    'Asia',
    'Europe',
    'Oceania',
];Code language: JavaScript (javascript)

When you pass or update this value, the FormTokenField component will update automatically with “tokens.”

The placeholder attributeOpens in a new window

placeholder={ __(
	'Enter hashtags separated by commas.',
	'quotes-dlx'
) }Code language: JavaScript (javascript)

The placeholder attribute is what displays if there currently isn’t any input.

Pin itWebShare

The tokenizeOnSpace attributeOpens in a new window

If passed true, when a user enters a space, it will create a token.

tokenizeOnSpace={ true }Code language: JavaScript (javascript)

The label attributeOpens in a new window

The label is simply what’s shown above the input field.

label={ __( 'Hashtags', 'quotes-dlx' ) }Code language: JavaScript (javascript)

The onChange attributeOpens in a new window

The onChange attribute triggers every time there’s an addition or removal of a token from the FormTokenField component.

Pin itWebShare

FormTokenField in BlocksOpens in a new window

Pin itWebShare

The way I used hashtags in the block editor is very similar to how I used the FormTokenField component in the admin.

Since we’re in the context of blocks, I’ll show you how I registered the block attributes. The following assumes you’re using block.json for your blocks.

Pin itWebShare

You’ll notice that the hashtags are of type array with a default of: []

And here’s the code for displaying and saving the attribute.

<FormTokenField
	value={ hashtags }
	placeholder={ __(
		'Enter hashtags separated by commas.',
		'quotes-dlx'
	) }
	className="quotes-dlx-hashtag-fields"
	tokenizeOnSpace={ true }
	label={ __( 'Hashtags', 'quotes-dlx' ) }
	onChange={ ( tokens ) => {
		const filteredTokens = [];
		tokens.forEach( function( item, index ) {
			const replacement = item.replace( '#', '' ); // Strip hashtag symbol.
			const hashtag = twttr.txt.extractHashtags(
				'#' + replacement
			); // Add it back in for extraction.
			// Check if array contains anything.
			if ( typeof hashtag[ 0 ] !== 'undefined' ) {
				filteredTokens.push( hashtag[ 0 ] );
			}
		} );
		setAttributes( { hashtags: filteredTokens } );
	} }
/>Code language: JavaScript (javascript)

You’ll notice at the very end of the onChange attribute, that I call setAttributes to save the hashtags in the block editor.

ConclusionOpens in a new window

The FormTokenField component is pretty useful if you have an array of tokens, tags, hashtags, etc. If you have any questions, I’ll reply in the comments.