The add_screen_option() WordPress PHP function is used to register and configure an admin screen option.
Usage
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">
Parameters
- $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.
Examples
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));
});