wp_dropdown_pages( array|string $args =  ): string

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

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.

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

    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

    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

    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

    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.