Content & Posts PHP Intermediate

Register Custom Post Statuses

Add custom statuses like 'In Review' and 'Approved' to the post editing workflow, giving editorial teams a structured approval process beyond WordPress's default Draft and Published states.

Tested on WordPress 7.1 PHP 8.3 No plugin needed Updated
functions.php 44 lines
add_action( 'init', function() {
    register_post_status( 'in_review', [
        'label'                     => 'In Review',
        'public'                    => false,
        'show_in_admin_all_list'    => true,
        'show_in_admin_status_list' => true,
        'label_count'               => _n_noop(
            'In Review <span class="count">(%s)</span>',
            'In Review <span class="count">(%s)</span>'
        ),
    ] );

    register_post_status( 'approved', [
        'label'                     => 'Approved',
        'public'                    => false,
        'show_in_admin_all_list'    => true,
        'show_in_admin_status_list' => true,
        'label_count'               => _n_noop(
            'Approved <span class="count">(%s)</span>',
            'Approved <span class="count">(%s)</span>'
        ),
    ] );
} );

// Add custom statuses to the post edit screen dropdown
add_action( 'post_submitbox_misc_actions', function() {
    global $post;
    $custom_statuses = [ 'in_review' => 'In Review', 'approved' => 'Approved' ];
    ?>
    <script>
    jQuery(document).ready(function($) {
        <?php foreach ( $custom_statuses as $slug => $label ) : ?>
        $('select#post_status').append(
            $('<option>').val('<?php echo esc_js( $slug ); ?>').text('<?php echo esc_js( $label ); ?>')
        );
        <?php if ( $post->post_status === $slug ) : ?>
        $('select#post_status').val('<?php echo esc_js( $slug ); ?>');
        $('#post-status-display').text('<?php echo esc_js( $label ); ?>');
        <?php endif; ?>
        <?php endforeach; ?>
    });
    </script>
    <?php
} );

Where to add this

Recommended A code snippets plugin Survives theme changes and is easy to switch off.
Child theme At the end of your child theme's functions.php file.
Must-use plugin As a .php file in wp-content/mu-plugins, starting with <?php.

Always add PHP to a staging site first, or have FTP or file manager access ready, so you can undo it if something goes wrong.

WordPress’s default post statuses, Draft, Pending Review, Published, Private, and Scheduled, cover the basics but don’t map well to multi-step editorial workflows. A publishing team might need content to pass through copywriting, fact-checking, legal review, and sign-off before publication. Custom post statuses let you formalise these steps directly in WordPress without a complex workflow plugin.

What the code does

The snippet registers two example statuses, In Review and Approved, and adds them to the status dropdown on the post edit screen via a small JavaScript injection.

register_post_status Arguments

public => false means posts with these statuses are not publicly accessible, they behave like drafts on the front end. Set to true only if posts in this status should be viewable by visitors, which is unusual for workflow statuses.

show_in_admin_all_list => true makes posts with these statuses appear in the All Posts view in the admin. Without this, they’d be hidden from the default list view and only visible when explicitly filtering by status.

show_in_admin_status_list => true adds the status as a tab above the posts list table, for example “In Review (4)”, so editors can filter posts by that status with a single click.

label_count with _n_noop() provides the singular and plural label format for the count displayed in the status tab.

Adding to the Edit Screen Dropdown

WordPress doesn’t automatically add custom statuses to the post editor’s status dropdown, that requires a JavaScript injection. The post_submitbox_misc_actions hook fires inside the Publish metabox on classic editor screens, making it the right place to add the script. The script appends options to the status select and, if the post is already in a custom status, sets the dropdown to reflect it and updates the visible status label.

Block Editor Compatibility

The JavaScript injection targets the classic editor’s status dropdown. In the block editor, the status control is a React component in the sidebar and requires a more involved approach, registering a plugin via @wordpress/plugins that adds custom status options to the block editor UI. For teams using the block editor, a dedicated workflow plugin like PublishPress may be a more practical solution.

Querying by Custom Status

To query posts in a custom status, pass the slug in the post_status argument: get_posts(['post_status' => 'in_review']). This works in WP_Query, get_posts, and REST API queries (when appropriately authenticated).

Block editor note

The block editor’s status menu only lists WordPress’s own statuses, so the dropdown changes in this snippet appear in the classic editor and Quick Edit only. In the block editor you can still filter the Posts list by your custom statuses, or set them with WP-CLI: wp post update 123 --post_status=in_review.

This website uses cookies to enhance your browsing experience and ensure the site functions properly. By continuing to use this site, you acknowledge and accept our use of cookies.

Accept All Accept Required Only