Modifiers

Modifiers are used to take action on any selected items in the view. They are shown contextually (below the search bar) when items are selected. They can also be shown in swipe actions on mobile. Index comes built-in with two modifiers: “Edit” and “Trash”.

Registering modifiers

New modifiers are registered for individual post types:

// replace ${type} with the post type name
wp.hooks.addFilter(
  `${type}_modifiers`,
	'index',
	function(modifiers) {
		return modifiers
	},
	20
)

Required values

id

An internal identifier string that can be anything. The ID should have a namespace at the beginning to avoid duplicates.

label

The button text displayed to the user. The label should be under 20 characters.

icon

Valid Index icon or a JSX SVG component. If you are using your own icon, it should be 18px by 18px with 1px of padding on all sides. See the icon documentation [LINK] for more information.

permission

Valid WordPress permission. Learn how to see all available permission values here [LINK].

onClick

Javascript function where you will perform your work. A set of props are passed back as an object to check selection, request confirmation, and set toast notifications.

---

Optional values

color

Valid Index color or CSS color. See the color documentation [LINK] for more on colors.

swipeable

Optionally show this modifier on mobile when swiping on items. Note that all custom modifiers are placed in a swipe action labeled “More”, which displays a popup. This is to prevent an unlimited number of swipe actions displaying in the main list.

---

onClick Props

The onClick parameter passes back a variety of props to help you quickly confirm the action and alert the viewer when the action is completed:

labels

An object with the full list of labels passed into all Index views.

post_type

The current post type name.

permissions

An object with the full list of permissions for the current user.

selected

An array of selected items. There should always be at least one item as modifiers are only displayed when there is a selection.

selectedAll

A boolean value if all items are selected. This can be useful when deciding to display the “requestConfirmation” option.

setNotification

A function to display a toast notification to the viewer. Usually used when the modifier code has completed.

requestConfirmation

A function to display a confirmation to the viewer before performing the action. Recommended when selectAll is true and the action is immediate. The function takes a props object with the following items:

• title: the modal title
• confirm_label: The modal button which will perform the action if clicked
• variant: The color style of the modal button. Options are:
  • Warning (default): a red button with white text
  • Primary: a blue button with white text
  • Normal: a grey button with black text
• onConfirm: a function to perform the modifier action when the viewer has confirmed that they want to perform it

Example modifier

The following will create a new, blue colored modifier for the Posts view, with a pencil icon and the label “Click me”. The onClick parameter is where you will do all of your work, and the examples shows some of the passed in options:

wp.hooks.addFilter(
  'post_modifiers',
	'index',
	function(modifiers) {
		return modifiers.concat([
			{
		    id: 'your-id',
		    label: 'Click me',
		    icon: 'pencil',
		    permission: 'edit',
		    color: 'blue',
		    onClick: function(props) {
					if(props.selectedAll) {
						props.requestConfirmation({
                title: 'Are you sure?',
                confirm_label: 'Yes',
                variant: 'warning',
                onConfirm: () => {
                    props.setNotification('you clicked me with everything selected!')
                }
            })
					} else {
						props.setNotification(`you clicked me with ${props.selected.length} selected`)
					}
				},
			}
		])
	},
	10
)

Resources

How to use wp_enqueue_script

Adding mobile swipe actions

Icon and color options