Using WordPress ‘add_screen_option()’ PHP function

The add_screen_option() WordPress PHP function is used to register and configure an admin screen option.


Here’s a generic example of how to use the function:

add_screen_option('per_page', array('label' => 'My Label', 'default' => 1, 'option' => 'option_name'));

This function will generate the following HTML:

<input type="number" step="1" min="1" max="999" class="screen-per-page" name="wp_screen_options[value]" id="option_name" maxlength="3" value="1">


  • $option (string) Required: The name of the option. It can be ‘per_page’ or ‘layout_columns’.
  • $args (array) Optional: Option-dependent arguments. Default is an empty array.

More information

See WordPress Developer Resources: add_screen_option()
The add_screen_option() function does not currently support the checkboxes method.


Setting the Number of Items per Page

This example sets the default number of items per page to 1 for a particular screen.

add_action('admin_init', function() {
    add_screen_option('per_page', array('label' => 'Items', 'default' => 1, 'option' => 'items_per_page'));

Setting the Number of Layout Columns

This example sets the number of layout columns to 2 for a specific screen.

add_action('admin_init', function() {
    add_screen_option('layout_columns', array('max' => 2, 'default' => 2));

Changing the Label of the Items per Page Option

In this example, we’re changing the label of the items per page option to “Posts”.

add_action('admin_init', function() {
    add_screen_option('per_page', array('label' => 'Posts', 'default' => 10, 'option' => 'posts_per_page'));

Setting a Minimum and Maximum Value for Items per Page

In this example, we’re setting a minimum and maximum value for the number of items per page.

add_action('admin_init', function() {
    add_screen_option('per_page', array('label' => 'Items', 'default' => 1, 'option' => 'items_per_page', 'min' => 1, 'max' => 999));

Changing Default Columns for Network Dashboard

Here we’re changing the default number of columns for the network dashboard to 2.

add_action('wp_network_dashboard_setup', function() {
    add_screen_option('layout_columns', array('default' => 2));