Skip to main content

benecaster_setup_wizard_steps

Filter Free

Filters the ordered array of step definitions passed to the Setup Wizard before the wizard shell is rendered. Add-ons use this filter to inject custom configuration steps, reorder existing steps, or conditionally remove steps based on site state.

Each step definition requires four keys: id (a unique slug used in completion tracking), component (the registered React component name), required (whether the step can be skipped), and condition (an optional state flag that must be true for the step to appear). Unrecognised condition strings default to false, so steps are safely hidden until their flag-setting logic is deployed. Benecaster step IDs for positioning, in order: language, show-name, artwork, description, category, details, subscribers, migration, ssp-import, subscription, builtin-stripe, builtin-tier, tiers, import, limit-enforcement, permalink, done.

The wizard renders a step’s component with three props: showId (the show being set up, null in the first-run wizard until the show has been created), lateRun (true only when the step was requested after setup with benecaster_request_wizard_step()) and setCanContinue( boolean ), which holds Continue → (or Finish →) disabled until the step releases it. Skip is never held. See Inject a step into the setup wizard from an add-on for the rules and a worked example.

The component must name a function on window.BenecasterExtensions. That object also carries Benecaster’s React runtime (React, ReactDOM, ReactDOMClient, ReactJSXRuntime, i18n, extensionRuntimeVersion), and the wizard renders a step only when the named value is callable, so do not name a component after one of those keys.

A step component may use React hooks when its bundle maps Benecaster’s runtime as externals, as described in Inject a React component into a named slot. Enqueue the step’s script with benecaster-wizard as a dependency, not benecaster-admin. The wizard does not publish ReactQuery or queryClient, so do not externalise @tanstack/react-query in a wizard bundle; fetch with window.fetch.

Parameters

Name Type Default Description
$steps array — Ordered array of step definition arrays

Returns: array

Examples

Inject step after RSS step

add_filter( 'benecaster_setup_wizard_steps', function( $steps ) {
    // Inject a custom "Analytics" step after the "RSS" step.
    $position = array_search( 'rss', array_column( $steps, 'id' ), true );
    $new_step = [ 'id' => 'analytics', 'label' => 'Analytics Setup', 'add_on' => 'my-analytics-addon' ];
    array_splice( $steps, $position !== false ? $position + 1 : count( $steps ), 0, [ $new_step ] );
    return $steps;
} );

Inject bridge-conditional step

add_filter( 'benecaster_setup_wizard_steps', function ( array $steps ): array {
    $insert_after = array_search( 'subscription', array_column( $steps, 'id' ), true );

    if ( false !== $insert_after ) {
        array_splice( $steps, $insert_after + 1, 0, [[
            'id'        => 'my-addon-config',
            'component' => 'MyAddonWizardStep',
            'required'  => false,
            'condition' => 'bridge_connected',
        ]] );
    }

    return $steps;
} );

Notes

Use array_search on array_column( $steps, 'id' ) to find the insertion point, then array_splice to insert. Always return the modified array. Unrecognised condition strings default to false — it is safe to deploy a step before its flag-setting logic exists. Three bridge condition flags are set when the user continues from the Subscription step: bridge_connected (any option chosen, Built-in membership included), builtin_chosen (Built-in membership chosen) and external_bridge_connected (any other membership plugin chosen). Use external_bridge_connected for a step that reads an external plugin's levels.

Affects

  • Setup Wizard

Related Recipes

Need this built rather than just documented? See our services →