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

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

Contents

Description
- See also
Parameters
Return
Source
Hooks
Related
- Uses
- Used By
Changelog
User Contributed Notes
- Feedback

Description

See also

get_pages()

Parameters

$args array|string Optional

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

File: wp-includes/post-template.php. View all references

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 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

Uses
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 uses Hide more uses

Used By

Used By
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	Render the control’s content.

Changelog

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 1 content

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

Contributed by Codex — 8 years ago
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 2 content

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

Contributed by John Dorner — 4 years ago
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 3 content

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

Contributed by ghoul — 4 years ago
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 4 content

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

Contributed by adiant — 7 years ago
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 );
```
Top ↑
Feedback
- to make “post_type” work you have to set “hierarchical” to true at the custom post type creation args — By The Three — 4 years ago
Log in to add feedback

You must log in before being able to contribute a note or feedback.