wp_dropdown_pages() – Function | Developer.WordPress.org

Retrieves or displays a list of pages as a dropdown (select list).

Description

Parameters

$argsarray|stringoptional

Array or string of arguments to generate a page dropdown. See get_pages() for additional arguments.

depth int
Maximum depth. Default 0.
child_of int
Page ID to retrieve child pages of. Default 0.
selected int|string
Value of the option that should be selected. Default 0.
echo bool|int
Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents. Default 1.
name string
Value for the 'name' attribute of the select element.
Default 'page_id'.
id string
Value for the 'id' attribute of the select element.
class string
Value for the 'class' attribute of the select element. Default: none.
Defaults to the value of $name.
show_option_none string
Text to display for showing no pages. Default empty (does not display).
show_option_no_change string
Text to display for "no change" option. Default empty (does not display).
option_none_value string
Value to use when no page is selected.
value_field string
Post field used to populate the 'value' attribute of the option elements. Accepts any valid post field. Default 'ID'.

More Arguments from get_pages( … $args )

Array or string of arguments to retrieve pages.

child_of int
Page ID to return child and grandchild pages of. Note: The value of $hierarchical has no bearing on whether $child_of returns hierarchical results. Default 0, or no restriction.
sort_order string
How to sort retrieved pages. Accepts 'ASC', 'DESC'. Default 'ASC'.
sort_column string
What columns to sort pages by, comma-separated. Accepts 'post_author', 'post_date', 'post_title', 'post_name', 'post_modified', 'menu_order', 'post_modified_gmt', 'post_parent', 'ID', 'rand', 'comment*count'.
'post*' can be omitted for any values that start with it.
Default 'post_title'.
hierarchical bool
Whether to return pages hierarchically. If false in conjunction with $child_of also being false, both arguments will be disregarded.
Default true.
exclude int[]
Array of page IDs to exclude.
include int[]
Array of page IDs to include. Cannot be used with $child_of, $parent, $exclude, $meta_key, $meta_value, or $hierarchical.
meta_key string
Only include pages with this meta key.
meta_value string
Only include pages with this meta value. Requires $meta_key.
authors string
A comma-separated list of author IDs.
parent int
Page ID to return direct children of. Default -1, or no restriction.
exclude_tree string|int[]
Comma-separated string or array of page IDs to exclude.
number int
The number of pages to return. Default 0, or all pages.
offset int
The number of pages to skip before returning. Requires $number.
Default 0.
post_type string
The post type to query. Default 'page'.
post_status string|array
A comma-separated list or array of post statuses to include.
Default 'publish'.

Default:''

Return

string HTML dropdown list of pages.

Source

function wp_dropdown_pages( $args = '' ) {
	$defaults = array(
		'depth'                 => 0,
		'child_of'              => 0,
		'selected'              => 0,
		'echo'                  => 1,
		'name'                  => 'page_id',
		'id'                    => '',
		'class'                 => '',
		'show_option_none'      => '',
		'show_option_no_change' => '',
		'option_none_value'     => '',
		'value_field'           => 'ID',
	);

	$parsed_args = wp_parse_args( $args, $defaults );

	$pages  = get_pages( $parsed_args );
	$output = '';
	// Back-compat with old system where both id and name were based on $name argument.
	if ( empty( $parsed_args['id'] ) ) {
		$parsed_args['id'] = $parsed_args['name'];
	}

	if ( ! empty( $pages ) ) {
		$class = '';
		if ( ! empty( $parsed_args['class'] ) ) {
			$class = " class='" . esc_attr( $parsed_args['class'] ) . "'";
		}

		$output = "<select name='" . esc_attr( $parsed_args['name'] ) . "'" . $class . " id='" . esc_attr( $parsed_args['id'] ) . "'>\n";
		if ( $parsed_args['show_option_no_change'] ) {
			$output .= "\t<option value=\"-1\">" . $parsed_args['show_option_no_change'] . "</option>\n";
		}
		if ( $parsed_args['show_option_none'] ) {
			$output .= "\t<option value=\"" . esc_attr( $parsed_args['option_none_value'] ) . '">' . $parsed_args['show_option_none'] . "</option>\n";
		}
		$output .= walk_page_dropdown_tree( $pages, $parsed_args['depth'], $parsed_args );
		$output .= "</select>\n";
	}

	/**
	 * Filters the HTML output of a list of pages as a dropdown.
	 *
	 * @since 2.1.0
	 * @since 4.4.0 `$parsed_args` and `$pages` added as arguments.
	 *
	 * @param string    $output      HTML output for dropdown list of pages.
	 * @param array     $parsed_args The parsed arguments array. See wp_dropdown_pages()
	 *                               for information on accepted arguments.
	 * @param WP_Post[] $pages       Array of the page objects.
	 */
	$html = apply_filters( 'wp_dropdown_pages', $output, $parsed_args, $pages );

	if ( $parsed_args['echo'] ) {
		echo $html;
	}

	return $html;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_dropdown_pages’, string $output, array $parsed_args, WP_Post[] $pages ): Filters the HTML output of a list of pages as a dropdown.

Uses	Description
walk_page_dropdown_tree()`wp-includes/post-template.php`	Retrieves HTML dropdown (select) content for page list.
get_pages()`wp-includes/post.php`	Retrieves an array of pages (or hierarchical post type items).
esc_attr()`wp-includes/formatting.php`	Escaping for HTML attributes.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Show 3 more Show less

Used by	Description
page_attributes_meta_box()`wp-admin/includes/meta-boxes.php`	Displays page attributes form fields.
WP_Posts_List_Table::inline_edit()`wp-admin/includes/class-wp-posts-list-table.php`	Outputs the hidden row displayed when inline editing
WP_Customize_Control::render_content()`wp-includes/class-wp-customize-control.php`	Renders the control’s content.

Changelog

Version	Description
4.3.0	The `$class` argument was added.
4.2.0	The `$value_field` argument was added.
2.1.0	Introduced.

User Contributed Notes

Skip to note 5 content

John Dorner 5 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
For this to work for custom post types, you must set
```
'hierarchical' => true
```
in the custom post type’s settings when you register_post_type that you are getting the dropdown for.
If you don’t want the custom post type to truly be hierarchical, ensure the 'supports' arg doesn’t include 'page-attributes'
Log in to add feedback
Skip to note 6 content

Codex 10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
Dropdown with submit button
Displays a hierarchical page dropdown list in HTML form with a submit button.
```
<li id="pages">
	<h2><?php _e('pages:'); ?></h2>
	<form action="<?php bloginfo('url'); ?>" method="get">
		<?php wp_dropdown_pages(); ?>
		<input type="submit" name="submit" value="view" />
	</form>
</li>
```
Log in to add feedback
Skip to note 7 content

Sachyya 5 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
Make dropdown list multiple select
This is useful when you want to make multiple select or using with select2.js kinda things.
```
add_filter( 'wp_dropdown_pages', 'wporg_domain_make_multiple_select_pages' );
function wporg_domain_make_multiple_select_pages( $output ) {
	return str_replace( '<select ', '<select multiple="multiple" ', $output );
}
```
Log in to add feedback
Skip to note 8 content

jon 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
In addition, $args can include ‘sort_column’ and other get_pages() parameters, as shown in the page_attributes_meta_box() source code:
```
    $dropdown_args = array(
            'post_type'        => $post->post_type,
            'exclude_tree'     => $post->ID,
            'selected'         => $post->post_parent,
            'name'             => 'parent_id',
            'show_option_none' => __('(no parent)'),
            'sort_column'      => 'menu_order, post_title',
            'echo'             => 0,
        );
    ...
    $pages = wp_dropdown_pages( $dropdown_args );
```
- to make “post_type” work you have to set “hierarchical” to true at the custom post type creation args
  
  The Three 5 years ago
Log in to add feedback

wp_dropdown_pages( array|string $args = '' ): string

In this article