Using WordPress ‘register_post_status()’ PHP function

by

The register_post_status() WordPress PHP function allows you to create or modify a post status based on the given parameters. The function accepts a string for the post status name and an optional array of arguments.

Usage

register_post_status( 'custom_status', array( 'label' => 'Custom Status' ) );

Parameters

  • $post_status (string) (Required): Name of the post status.
  • $args (array|string) (Optional): Array or string of post status arguments. Possible keys include:
    • label (bool|string): A descriptive name for the post status marked for translation. Defaults to the value of $post_status.
    • label_count (array|false): Nooped plural text from _n_noop() to provide the singular and plural forms of the label for counts.
    • exclude_from_search (bool): Whether to exclude posts with this post status from search results.
    • _builtin (bool): Whether the status is built-in. For core-use only.
    • public (bool): Whether posts of this status should be shown in the front end of the site.
    • internal (bool): Whether the status is for internal use only.
    • protected (bool): Whether posts with this status should be protected.
    • private (bool): Whether posts with this status should be private.
    • publicly_queryable (bool): Whether posts with this status should be publicly-queryable.
    • show_in_admin_all_list (bool): Whether to include posts in the edit listing for their post type.
    • show_in_admin_status_list (bool): Show in the list of statuses with post counts at the top of the edit listings.
    • date_floating (bool): Whether the post has a floating creation date.

More information

See WordPress Developer Resources: register_post_status()

Examples

Registering a Basic Custom Status

Register a custom post status named ‘in_review’ with a label ‘In Review’:

function create_custom_post_status() {
    register_post_status( 'in_review', array(
        'label' => 'In Review'
    ));
}
add_action( 'init', 'create_custom_post_status' );

Registering a Custom Status with More Options

Register a custom post status named ‘archived’ with more options:

function create_archived_post_status() {
    register_post_status( 'archived', array(
        'label' => 'Archived',
        'public' => true,
        'exclude_from_search' => true,
        'show_in_admin_all_list' => true,
        'show_in_admin_status_list' => true
    ));
}
add_action( 'init', 'create_archived_post_status' );

Registering a Custom Status with a Translatable Label

Register a custom post status named ‘pending_review’ with a translatable label:

function create_pending_review_post_status() {
    register_post_status( 'pending_review', array(
        'label' => __( 'Pending Review', 'textdomain' )
    ));
}
add_action( 'init', 'create_pending_review_post_status' );

Registering a Custom Status with Label Count

Register a custom post status named ‘on_hold’ with a label count:

function create_on_hold_post_status() {
    register_post_status( 'on_hold', array(
        'label' => 'On Hold',
        'label_count' => _n_noop( 'On Hold (%