WordPress.org
Get WordPress
WordPress.org

WordPress Developer Resources

wp_dropdown_pages()

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

In this article

Back to top

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

Description

See also

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.

UsesDescription
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 moreShow less
Used byDescription
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

VersionDescription
4.3.0The $class argument was added.
4.2.0The $value_field argument was added.
2.1.0Introduced.

User Contributed Notes

  1. Skip to note 5 content
    John Dorner
    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'

  2. Skip to note 6 content
    Codex
    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>
  3. Skip to note 7 content
    Sachyya
    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 ); }
  4. Skip to note 8 content
    jon
    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 );

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