Search by

arraypress / wp-register-onboarding

arraypress

First-run setup wizards and setup checklists for WordPress plugins, described as steps and tasks, with fields rendered by the field kit.

Package info

github.com/arraypress/wp-register-onboarding

pkg:composer/arraypress/wp-register-onboarding

Statistics

Installs: 26

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

v1.0.0 2026-08-25 15:55 UTC

This package is auto-updated.

Last update: 2026-11-18 10:54:16 UTC


README

This library has moved. It is now part of sugarcommerce/onboarding (namespace SugarCommerce\Onboarding, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.

Register Onboarding

A first-run setup wizard and a setup checklist for a WordPress plugin, described as steps and tasks rather than built as screens.

What it does

The first five minutes after activation decide whether a plugin gets used. Shopify, Stripe and WooCommerce all answer them the same way: a short, calm wizard that asks one thing per screen, then a checklist that stays on the dashboard until the rest is done. Building that means a multi-step form, progress, validation, resume, buttons that test things without leaving the page, somewhere to keep the answers, a redirect on activation, and a card that knows which tasks are done.

This is that, from a list of steps and a list of tasks. The fields are the field kit's, so every control matches the rest of the admin, and answers land in the option your settings screen already reads.

Features

  • Ask one question per screen, with any field the field kit draws
  • Save answers straight into the option your settings page reads
  • Refuse a step until it is right, with each message beside its field
  • Show a step only when an earlier answer calls for it
  • Let people skip a step, or save and finish later, and pick up where they left off
  • Test a key or create pages from a button, without leaving the step
  • Keep a setup checklist on the dashboard until every task is done
  • Open the wizard once on activation, and run it again from anywhere

Installation

composer require arraypress/wp-register-onboarding

Quick start

add_action( 'init', function () {
	register_onboarding( 'myshop-setup', [
		'title'    => __( 'Set up My Shop', 'my-shop' ),
		'option'   => 'myshop_settings',
		'redirect' => true,
		'steps'    => [
			'welcome' => [
				'title'       => __( 'Welcome to My Shop', 'my-shop' ),
				'description' => __( 'Three questions and your shop is ready for a test sale.', 'my-shop' ),
			],
			'store'   => [
				'title'  => __( 'Your store', 'my-shop' ),
				'fields' => [
					'store_name' => [
						'type'     => 'text',
						'label'    => __( 'Store name', 'my-shop' ),
						'required' => true,
					],
					'country'    => [
						'type'  => 'country',
						'label' => __( 'Country', 'my-shop' ),
					],
				],
			],
		],
	] );
} );

register_activation_hook( __FILE__, function () {
	onboarding_redirect_after_activation( 'myshop-setup' );
} );

'option' => 'myshop_settings' is the part worth noticing: answers go into the option your settings page already uses, so the wizard is a friendlier way into the same values rather than a second copy of them.

Contents

Steps

A step is a screen. Any step may hold any of these, drawn top to bottom: image, content (filtered through wp_kses_post()), items (an icon and a line or two each), a render callback, fields, and links. A step with only content explains; one with only fields asks.

'steps' => [
	'welcome' => [
		'title'       => __( 'Welcome', 'my-shop' ),
		'description' => __( 'A few minutes now and you are ready to sell.', 'my-shop' ),
		'items'       => [
			[ 'icon' => 'heroicons-outline:building-storefront', 'title' => __( 'Your store', 'my-shop' ), 'description' => __( 'Name and country.', 'my-shop' ) ],
			[ 'icon' => 'admin-network', 'title' => __( 'Payments', 'my-shop' ), 'description' => __( 'Paste a key and test it.', 'my-shop' ) ],
		],
		'button'      => __( 'Get Started', 'my-shop' ),
	],
],

An item's icon takes either form the field kit's Icons::render() reads: a set:name icon (heroicons-outline:building-storefront, any set the kit has), drawn as inline SVG in the accent colour, or a Dashicon by its name or its class (admin-network, dashicons-admin-network), drawn as the font's span. With no icon, or one no set has, an item has a tick (heroicons-outline:check). The wizard's and the checklist's own icons -- the ticks and dashes in the progress, Back, Show All, the dismiss cross, the mark on a link that opens a new tab -- are Heroicons outline too.

short_title is what the progress calls a step whose title is a sentence. button renames Continue for one step. The wizard's own wording is in labels — next, back, skip, finish, later and exit — for a plugin that wants its own voice or its own translations.

Fields

Every type the field kit registers works in a step, from text to repeater, email_editor and license, and is stored as the kit sanitizes it. Media fields open the media library, relational fields search, conditional fields (show_when) hide and are cleared when hidden. See the kit's README for the types and their options.

'payments' => [
	'title'  => __( 'Payments', 'my-shop' ),
	'fields' => [
		'currency'  => [
			'type'    => 'currency',
			'label'   => __( 'Currency', 'my-shop' ),
			'default' => 'GBP',
		],
		'test_mode' => [
			'type'        => 'toggle',
			'label'       => __( 'Test mode', 'my-shop' ),
			'default'     => 1,
			'description' => __( 'Nothing real is charged while this is on.', 'my-shop' ),
		],
		'secret'    => [
			'type'   => 'password',
			'label'  => __( 'Secret key', 'my-shop' ),
			'reveal' => true,
		],
	],
],

A password box left empty keeps what is stored, as it does on a settings page.

Where answers are stored

Four arrangements, from the most common:

// Every answer in one option, as a settings array.
'option' => 'myshop_settings',

// The plugin's own getter and setter, for settings that are encrypted,
// validated or spread across several stores.
'get_callback'    => fn( string $key ) => myshop_get_setting( $key ),
'update_callback' => fn( string $key, $value ) => myshop_update_setting( $key, $value ),

// Any field-kit context.
'context' => new \ArrayPress\FieldKit\Context\OptionContext( 'myshop_settings' ),

// Nothing: an option per field, named by its key or by its own `option`.

A step can store its answers itself with save, which is handed the sanitized answers and the wizard. Returning a WP_Error or a message stops the step with it:

'save' => function ( array $values ) {
	return myshop_create_account( $values ) ? true : new WP_Error( 'account', __( 'The account could not be created.', 'my-shop' ) );
},

Progress — which steps were answered, skipped, where to pick up, whether it was finished — is kept apart, in {id}_onboarding (or state_option), so running the wizard again keeps every answer.

Validation

A step passes or fails whole: nothing is stored until every check passes.

The kit refuses a field that is required and empty, or that breaks its own validate rule — a rule name (email, url, numeric, integer, slug, alphanumeric) or a callable answering true or a message.

The step's own validate sees every answer together, and the wizard:

'limits' => [
	'title'    => __( 'Order limits', 'my-shop' ),
	'fields'   => [
		'minimum' => [ 'type' => 'number', 'label' => __( 'Smallest order', 'my-shop' ) ],
		'maximum' => [ 'type' => 'number', 'label' => __( 'Largest order', 'my-shop' ) ],
	],
	'validate' => function ( array $values, $wizard ) {
		if ( $values['minimum'] > $values['maximum'] ) {
			return [ 'maximum' => __( 'The largest order has to be at least the smallest.', 'my-shop' ) ];
		}

		return true;
	},
],

It may answer:

Answer Means
true, null, nothing Pass
false Refuse the step with a general message
a string Refuse the step with that message
WP_Error Each code that names a field puts its message beside that field; any other code is about the step
an array Messages keyed by field, or by anything else for the step

A refused step comes back showing what was typed, with a list of what to fix at the top — each a link to its field — and each message again beside its field. arraypress_onboarding_validate_{id} can add to or clear the list.

Conditional steps

A step with a show_if that says no is absent: not counted, not reachable by its URL, and a submission naming it is refused. Either a callable, handed the wizard, or a field-kit condition over answers already saved:

'shipping' => [
	'title'   => __( 'Shipping', 'my-shop' ),
	'show_if' => [ 'sells' => [ 'physical', 'both' ] ],
	'fields'  => [
		'ship_from' => [ 'type' => 'country', 'label' => __( 'Ship from', 'my-shop' ) ],
	],
],

'tax' => [
	'title'   => __( 'Tax', 'my-shop' ),
	'show_if' => fn( $wizard ) => 'EU' === myshop_region_of( $wizard->value( 'country' ) ),
],

The long form takes an operator: [ 'field' => 'orders', 'operator' => '>', 'value' => 100 ].

Skip, finish later and resume

'extras' => [
	'title'      => __( 'Extras', 'my-shop' ),
	'skippable'  => true,
	'skip_label' => __( 'Not Now', 'my-shop' ),
	'fields'     => [ /* … */ ],
],

Skip stores nothing and remembers the step as skipped, so the progress says so and the step is there to come back to. Save and Finish Later stores the step if it passes and leaves to exit_url. Opening the wizard again, by its URL or from the checklist, lands on the first step nobody has dealt with. Steps already dealt with are links in the progress; steps ahead cannot be opened by URL, since they may depend on an answer not given yet.

Buttons that do something

A "Test Connection" or "Create Pages" button is the kit's action_button. It runs over REST and reports in place, and it is handed every answer on the step as typed — before anything is saved — under each field's key:

'fields' => [
	'api_key' => [
		'type'  => 'password',
		'label' => __( 'API key', 'my-shop' ),
	],
	'test'    => [
		'type'            => 'action_button',
		'label'           => __( 'Check the key', 'my-shop' ),
		'button_label'    => __( 'Test Connection', 'my-shop' ),
		'action_callback' => function ( array $payload ) {
			$key = $payload['api_key'] ?: myshop_get_setting( 'api_key' );

			return myshop_ping( $key )
				? [ 'success' => true, 'message' => __( 'Connected.', 'my-shop' ) ]
				: [ 'success' => false, 'message' => __( 'That key did not work.', 'my-shop' ) ];
		},
	],
],

The handler is declared on rest_api_init for every step, so a press always finds it. Whoever may run the wizard may press its buttons; a field that wants a stricter rule sets action_capability.

Custom markup

For what fields cannot express — a list of the pages a button will make, a webhook address with its events — render draws inside the step, above its fields:

'pages' => [
	'title'  => __( 'Your pages', 'my-shop' ),
	'render' => function ( array $step, $wizard ) {
		echo '<ul>';
		foreach ( myshop_required_pages() as $page ) {
			printf( '<li>%s</li>', esc_html( $page['title'] ) );
		}
		echo '</ul>';
	},
],

Markup between two fields is the kit's html field. A step with a type this library does not know is handed to arraypress_onboarding_render_{type}, and sync draws a wp-inline-sync import, with Continue waiting for it.

The finish screen

Finishing the last step shows a finish screen: a tick, a heading, optional content, a checklist and somewhere to go. Opening a finished wizard lands there too.

'finish' => [
	'title'     => __( 'Your shop is ready for a test sale', 'my-shop' ),
	'checklist' => 'myshop-guide',
	'links'     => [
		[ 'label' => __( 'Go to Orders', 'my-shop' ), 'url' => admin_url( 'admin.php?page=myshop-orders' ) ],
		[ 'label' => __( 'Read the Guide', 'my-shop' ), 'url' => 'https://example.com/docs', 'external' => true ],
	],
	'confetti'  => true,
],

'finish' => false goes straight to exit_url instead, and completed_redirect sends a finished wizard anywhere.

The setup checklist

A card of tasks that stays until they are done. Each task says how to tell — "Add your first product" is done when a product exists — so the card is never out of date: delete the only product and the task comes back.

register_onboarding_checklist( 'myshop-guide', [
	'title'            => __( 'Get your shop ready', 'my-shop' ),
	'description'      => __( 'Each task ticks itself off when it is done.', 'my-shop' ),
	'wizard'           => 'myshop-setup',
	'dashboard_widget' => __( 'Shop setup', 'my-shop' ),
	'tasks'            => [
		'product' => [
			'title'       => __( 'Add your first product', 'my-shop' ),
			'description' => __( 'A name, a price and a file is enough.', 'my-shop' ),
			'done'        => fn() => myshop_count_products() > 0,
			'url'         => admin_url( 'admin.php?page=myshop-products&action=new' ),
			'button'      => __( 'Add Product', 'my-shop' ),
		],
		'domain'  => [
			'title' => __( 'Connect your domain', 'my-shop' ),
			// No `done`: ticked by hand, with a Mark as Done button.
		],
		'theme'   => [
			'title'    => __( 'Pick a theme', 'my-shop' ),
			'optional' => true,
			'done'     => fn() => 'twentytwentysix' !== get_stylesheet(),
		],
	],
] );

Then wherever it belongs — a plugin's dashboard, an empty list:

add_action( 'admin_enqueue_scripts', fn() => enqueue_onboarding_checklist( 'myshop-guide' ) );

render_onboarding_checklist( 'myshop-guide' );
  • done is a callable; only an answer of exactly true is done, so a check that returns a count has to say what it means. With no done, a task is ticked by hand and the tick is stored for the site.
  • optional tasks are counted but do not hold the list back from complete.
  • show_if is a callable; a task that says no is not on the list.
  • wizard adds a Continue Setup button while that wizard is unfinished.
  • dashboard_widget — true, or the widget's title — puts the card on the WordPress dashboard.
  • The first task not done is open, with its button; the rest are a native accordion.
  • Dismissing hides the card for that person only, with an undo. dismissible => false keeps it; hide_when_complete => true removes it once every required task is done.
  • get_onboarding_checklist_status() answers where it stands — done, total, percent, complete, the next task and each task — for an API, an ability or a command-line tool. The next task is the first required one not done; an optional task is only next once nothing required is left.

Compact

On a screen people open every day — a list of orders — the full card pushes the work they came for below the fold on every visit. The compact layout is the same card folded to one row, about the height of a WordPress notice:

render_onboarding_checklist( 'myshop-guide', [ 'layout' => 'compact' ] );

Get your shop ready · 3 of 7 done ▬▬▬── │ Next: Add your shop's details [Add Details] · [Continue Setup] · Show All ⌄ · ×

  • The row has the title, the count with a slim bar, the next task with its button (or Mark as Done for a task ticked by hand), Continue Setup while the wizard is unfinished, Show All, and the dismiss button.
  • Show All opens the whole list under the row, in place. Whether it is open is remembered per person (is_expanded(), expand()), so somebody who wants the list in view keeps it.
  • Ticking, dismissing and bringing the card back keep the layout.
  • At phone width the row becomes three short lines: title and count beside the dismiss button, the next task, then the controls.

'layout' => 'full' is the default, and is what the wizard's finish screen and the dashboard widget draw.

Redirect on activation

register_activation_hook( __FILE__, fn() => onboarding_redirect_after_activation( 'myshop-setup' ) );

The wizard has to say 'redirect' => true as well, so turning it off is one line. It happens once, never to a finished wizard, never in a bulk activation, never to somebody who may not run it, and arraypress_onboarding_redirect_{id} can say no.

Running it again

reset_onboarding( 'myshop-setup' );               // Progress only; answers stay.
wp_safe_redirect( get_onboarding_url( 'myshop-setup' ) );

get_onboarding_url( 'myshop-setup', 'payments' ); // Open at a step.
is_onboarding_completed( 'myshop-setup' );
get_onboarding_progress( 'myshop-setup' );        // Counts, resume step, each step's status.

A "Run Setup Again" button on a Tools screen is those first two lines behind a nonce.

Who may run it

capability (default manage_options) decides who may open the wizard, submit it, press its buttons and read its progress. A checklist has its own capability. Every submission carries a nonce for its own wizard and step, and every REST route needs a signed-in user with the capability and a REST nonce.

Several wizards on one site

Two plugins can each have a wizard and a checklist. Everything either stores — the page, the input names, the nonces, the progress, the answers, the activation flag, the dismissals — is named from its own id. Assets load only on the wizard's own screen. In a Strauss-prefixed build the script handles, the REST namespace and the transients carry the plugin's prefix as well, so two bundled copies never answer for each other.

Layout

'layout' => 'focus', // or 'admin'

focus (the default) takes the admin menu, toolbar and footer away and puts the plugin's name and a way out across the top, as Shopify's, Stripe's and WooCommerce's first runs do: a first run is a funnel, and twenty menu items beside it are twenty ways out. It is still an admin page, so the media modal, colour picker and every script a field needs load as usual.

admin keeps the menu, for a wizard that is one tool among others.

'progress' => 'top', // or 'side'

top (the default) is one column: "Step 2 of 5 · Your shop" and a slim bar of one segment per step above the card, the card centred under it. A segment is solid when done, half full where you are, hatched when skipped and empty when still to come — different shapes, not only different colours — with each step's name under its segment on a wide screen and done steps linked back. Under 720px the names go and the count says where you are. side puts the steps in a rail beside the card instead, for a wizard with many steps whose names are worth seeing at once; on a narrow screen it folds to a count and a bar above the card. Either way the steps are an ordered list with the current one marked, so a screen reader hears the same thing.

parent_slug (default index.php) and hidden (default true) decide where the page hangs; logo, title, page_title and menu_title what it is called; notices (default false) whether other plugins' notices show on it.

Styling

The look matches the flyout library: a grey surface, a white card, rounded controls, and colour from the admin scheme. A plugin brands it with accent, or with custom properties rather than overriding rules:

'accent' => '#7c3aed',
.onboarding {
	--onboarding-accent: #7c3aed;
	--onboarding-card-radius: 16px;
	--onboarding-width: 720px;
}

.onboarding-checklist {
	--onboarding-checklist-accent: #7c3aed;
}

Every token is listed at the top of assets/css/onboarding.css and assets/css/checklist.css. body_class adds a class of the plugin's own to the wizard's page.

Hooks

Every hook carries the wizard's or checklist's id, so a plugin hears only its own.

Hook Type Arguments
arraypress_onboarding_steps_{id} filter $steps, $wizard — add, remove or reorder steps
arraypress_onboarding_step_applies_{id} filter $applies, $key, $step, $wizard
arraypress_onboarding_validate_{id} filter $errors, $key, $values, $wizard
arraypress_onboarding_values_{id} filter $values, $key, $wizard — before storing
arraypress_onboarding_step_saved_{id} action $key, $values, $wizard
arraypress_onboarding_step_skipped_{id} action $key, $wizard
arraypress_onboarding_completed_{id} action $wizard
arraypress_onboarding_completed_redirect_{id} filter $url, $wizard
arraypress_onboarding_reset_{id} action $wizard
arraypress_onboarding_redirect_{id} filter $redirect, $wizard — after activation
arraypress_onboarding_before_step_{id} action $key, $step, $wizard — inside the form
arraypress_onboarding_after_step_{id} action $key, $step, $wizard
arraypress_onboarding_render_{type} action $step, $wizard — a step type of your own
arraypress_onboarding_checklist_tasks_{id} filter $tasks, $checklist — add, remove or reorder tasks
arraypress_onboarding_checklist_task_done_{id} filter $done, $key, $task, $checklist
arraypress_onboarding_checklist_status_{id} filter $status, $checklist
arraypress_onboarding_checklist_task_marked_{id} action $key, $done, $checklist
arraypress_onboarding_checklist_dismissed_{id} action $dismissed, $user_id, $checklist

Functions

Function Does
register_onboarding( $id, $config ) Register a wizard
get_onboarding( $id ) The Wizard
get_onboarding_url( $id, $step = '' ) Its URL, where it left off or at a step
get_onboarding_progress( $id ) Counts, resume step and each step's status
is_onboarding_completed( $id ) Whether it was finished
reset_onboarding( $id ) Run it again, answers kept
onboarding_redirect_after_activation( $id ) Open it once, from an activation hook
unregister_onboarding( $id ) Forget it
register_onboarding_checklist( $id, $config ) Register a checklist
get_onboarding_checklist( $id ) The Checklist
render_onboarding_checklist( $id, $args = [] ) Draw its card
enqueue_onboarding_checklist( $id ) Load the card's assets in the head
get_onboarding_checklist_status( $id ) Where it stands
is_onboarding_checklist_complete( $id ) Whether every required task is done
unregister_onboarding_checklist( $id ) Forget it

REST routes

Under onboarding/v1 (or {prefix}-onboarding/v1 in a prefixed build). Each needs a signed-in user with the capability, and a REST nonce.

Route Method Does
/checklists/{id} GET The checklist's status, and whether this person dismissed it
/checklists/{id}/dismiss POST dismissed: true|false — hide or bring back the card
/checklists/{id}/tasks/{task} POST done: true|false — tick a task ticked by hand
/checklists/{id}/expanded POST expanded: true|false — keep the compact card's list open for this person
/wizards/{id} GET The wizard's progress

Buttons in steps run through the field kit's own action route.

Accessibility

  • Focus moves to each step's heading when it opens, so a screen reader starts at the question; to the list of errors when a step comes back refused.
  • Errors are an alert, each a link that moves focus to its field, and said again beside the field with aria-invalid and aria-describedby.
  • Continue is the first button in the form, so Enter means Continue; Skip and Save and Finish Later skip the browser's own checks.
  • The progress is an ordered list with aria-current="step"; done and skipped are said, not only drawn, and told apart by shape as well as colour.
  • The checklist is a native accordion; its bar is a labelled progressbar; ticking and dismissing are announced and keep the focus in place.
  • The compact card's Show All is a button with aria-expanded and aria-controls; its row reads, and tabs, in the order it is drawn, with the list straight after the button that opens it.
  • Everything works from the keyboard, at phone width, right to left, and with reduced motion (no confetti, no transitions). Nothing is loaded from another site.

Translation

Every string the library shows is in the arraypress text domain. A plugin that wants its own wording, or its own translations, passes labels to the wizard and checklist and writes its own titles.

Requirements

  • PHP 8.3 or later
  • WordPress 7.1 or later

License

GPL-2.0-or-later