wp_dropdown_categories

Display or retrieve the HTML dropdown list of categories.

Description

(string) wp_dropdown_categories( (string) $args = '' ); 

The hierarchical argument, which is disabled by default, will override the depth argument, unless it is true. When the argument is false, it will display all of the categories. When it is enabled it will use the value in the depth argument.

Returns (string)

HTML content only if 'echo' argument is 0.

Parameters (1)

0. $args — Optional. (string) => ''
Array or string of arguments to generate a categories drop-down element.

Options

  • show_option_all (string) => ''

    Text to display for showing all categories.

  • show_option_none (string) => ''

    Text to display for showing no categories.

  • option_none_value (string) => ''

    Value to use when no category is selected.

  • orderby (string) => 'id'

    Which column to use for ordering categories. See get_terms() for a list of accepted values.

  • order (string) => 'ASC'

    Whether to order terms in ascending or descending order. Accepts ASC or DESC..

  • pad_counts (bool) => false

    See get_terms() for an argument description.

  • show_count (bool|int) => 0

    Whether to include post counts. Accepts 0, 1, or their bool equivalents.

  • hide_empty (bool|int) => 1

    Whether to hide categories that don't have any posts. Accepts 0, 1, or their bool equivalents.

  • child_of (int) => 0

    Term ID to retrieve child terms of. See get_terms().

  • exclude (array|string) => array()

    Array or comma/space-separated string of term ids to exclude. If $include is non-empty, $exclude is ignored.

  • echo (bool|int) => 1

    Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents.

  • hierarchical (bool|int) => 0

    Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool equivalents.

  • depth (int) => 0

    Maximum depth.

  • tab_index (int) => 0 (no tabindex)

    Tab index for the select element.

  • name (string) => 'cat'

    Value for the name attribute of the select element.

  • id (string) => 'to the value of $name'

    Value for the id attribute of the select element.

  • class (string) => 'postform'

    Value for the class attribute of the select element.

  • selected (int|string) => ''

    Value of the option that should be selected.

  • value_field (string) => 'term_id'

    Term field that should be used to populate the value attribute of the option elements. Accepts any valid term field: term_id,, name., slug, term_group, term_taxonomy_id, taxonomy, description, parent, count.

  • taxonomy (string|array) => 'category'

    Name of the category or categories to retrieve.

  • hide_if_empty (bool) => false (create select element even if no categories are found)

    True to skip generating markup if no categories are found.

array(

    /**
     * Text to display for showing all categories.
     *
     * @type string
     * @default ''
     */
    'show_option_all' => '',

    /**
     * Text to display for showing no categories.
     *
     * @type string
     * @default ''
     */
    'show_option_none' => '',

    /**
     * Value to use when no category is selected.
     *
     * @type string
     * @default ''
     */
    'option_none_value' => '',

    /**
     * Which column to use for ordering categories. See get_terms() for a list of accepted values.
     *
     * @type string
     * @default 'id'
     */
    'orderby' => 'id',

    /**
     * Whether to order terms in ascending or descending order. Accepts 'ASC' or 'DESC'.
     *
     * @type string
     * @default 'ASC'
     */
    'order' => 'ASC',

    /**
     * See get_terms() for an argument description.
     *
     * @type bool
     * @default false
     */
    'pad_counts' => false,

    /**
     * Whether to include post counts. Accepts 0, 1, or their bool equivalents.
     *
     * @type bool|int
     */
    'show_count' => 0,

    /**
     * Whether to hide categories that don't have any posts. Accepts 0, 1, or their bool equivalents.
     *
     * @type bool|int
     * @default 1
     */
    'hide_empty' => 1,

    /**
     * Term ID to retrieve child terms of. See get_terms().
     *
     * @type int
     */
    'child_of' => 0,

    /**
     * Array or comma/space-separated string of term ids to exclude. If `$include` is non-empty,
     * `$exclude` is ignored.
     *
     * @type array|string
     * @default array()
     */
    'exclude' => array(),

    /**
     * Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents.
     *
     * @type bool|int
     * @default 1
     */
    'echo' => 1,

    /**
     * Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool equivalents.
     *
     * @type bool|int
     */
    'hierarchical' => 0,

    /**
     * Maximum depth.
     *
     * @type int
     */
    'depth' => 0,

    /**
     * Tab index for the select element.
     *
     * @type int
     * @default 0 (no tabindex)
     */
    'tab_index' => 0 (no tabindex),

    /**
     * Value for the 'name' attribute of the select element.
     *
     * @type string
     * @default 'cat'
     */
    'name' => 'cat',

    /**
     * Value for the 'id' attribute of the select element.
     *
     * @type string
     * @default 'to the value of $name'
     */
    'id' => 'to the value of $name',

    /**
     * Value for the 'class' attribute of the select element.
     *
     * @type string
     * @default 'postform'
     */
    'class' => 'postform',

    /**
     * Value of the option that should be selected.
     *
     * @type int|string
     * @default ''
     */
    'selected' => '',

    /**
     * Term field that should be used to populate the 'value' attribute of the option elements.
     * Accepts any valid term field: 'term_id', 'name', 'slug', 'term_group',
     * 'term_taxonomy_id', 'taxonomy', 'description', 'parent', 'count'.
     *
     * @type string
     * @default 'term_id'
     */
    'value_field' => 'term_id',

    /**
     * Name of the category or categories to retrieve.
     *
     * @type string|array
     * @default 'category'
     */
    'taxonomy' => 'category',

    /**
     * True to skip generating markup if no categories are found.
     *
     * @type bool
     * @default false (create select element even if no categories are found)
     */
    'hide_if_empty' => false (create select element even if no categories are found)
);        


Usage

  1. if ( !function_exists( 'wp_dropdown_categories' ) ) { 
  2. require_once ABSPATH . WPINC . '/category-template.php'; 
  3.  
  4. // Optional. Array or string of arguments to generate a categories drop-down element. 
  5. $args = array( 
  6. 'show_option_all' => '', 
  7. 'show_option_none' => '', 
  8. 'option_none_value' => '', 
  9. 'orderby' => 'id', 
  10. 'order' => 'ASC', 
  11. 'pad_counts' => false, 
  12. 'show_count' => 0, 
  13. 'hide_empty' => 1, 
  14. 'child_of' => 0, 
  15. 'exclude' => array(), 
  16. 'echo' => 1, 
  17. 'hierarchical' => 0, 
  18. 'depth' => 0, 
  19. 'tab_index' => 0 (no tabindex), 
  20. 'name' => 'cat', 
  21. 'id' => 'to the value of $name', 
  22. 'class' => 'postform', 
  23. 'selected' => '', 
  24. 'value_field' => 'term_id', 
  25. 'taxonomy' => 'category', 
  26. 'hide_if_empty' => false (create select element even if no categories are found) 
  27. ); 
  28.  
  29. // NOTICE! Understand what this does before running. 
  30. $result = wp_dropdown_categories($args); 
  31.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/category-template.php  
  1. function wp_dropdown_categories( $args = '' ) { 
  2. $defaults = array( 
  3. 'show_option_all' => '',  
  4. 'show_option_none' => '',  
  5. 'orderby' => 'id',  
  6. 'order' => 'ASC',  
  7. 'show_count' => 0,  
  8. 'hide_empty' => 1,  
  9. 'child_of' => 0,  
  10. 'exclude' => '',  
  11. 'echo' => 1,  
  12. 'selected' => 0,  
  13. 'hierarchical' => 0,  
  14. 'name' => 'cat',  
  15. 'id' => '',  
  16. 'class' => 'postform',  
  17. 'depth' => 0,  
  18. 'tab_index' => 0,  
  19. 'taxonomy' => 'category',  
  20. 'hide_if_empty' => false,  
  21. 'option_none_value' => -1,  
  22. 'value_field' => 'term_id',  
  23. 'required' => false,  
  24. ); 
  25.  
  26. $defaults['selected'] = ( is_category() ) ? get_query_var( 'cat' ) : 0; 
  27.  
  28. // Back compat. 
  29. if ( isset( $args['type'] ) && 'link' == $args['type'] ) { 
  30. /** translators: 1: "type => link", 2: "taxonomy => link_category" alternative */ 
  31. _deprecated_argument( __FUNCTION__, '3.0.0',  
  32. sprintf( __( '%1$s is deprecated. Use %2$s instead.' ),  
  33. '<code>type => link</code>',  
  34. '<code>taxonomy => link_category</code>' 
  35. ); 
  36. $args['taxonomy'] = 'link_category'; 
  37.  
  38. $r = wp_parse_args( $args, $defaults ); 
  39. $option_none_value = $r['option_none_value']; 
  40.  
  41. if ( ! isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) { 
  42. $r['pad_counts'] = true; 
  43.  
  44. $tab_index = $r['tab_index']; 
  45.  
  46. $tab_index_attribute = ''; 
  47. if ( (int) $tab_index > 0 ) { 
  48. $tab_index_attribute = " tabindex=\"$tab_index\""; 
  49.  
  50. // Avoid clashes with the 'name' param of get_terms(). 
  51. $get_terms_args = $r; 
  52. unset( $get_terms_args['name'] ); 
  53. $categories = get_terms( $r['taxonomy'], $get_terms_args ); 
  54.  
  55. $name = esc_attr( $r['name'] ); 
  56. $class = esc_attr( $r['class'] ); 
  57. $id = $r['id'] ? esc_attr( $r['id'] ) : $name; 
  58. $required = $r['required'] ? 'required' : ''; 
  59.  
  60. if ( ! $r['hide_if_empty'] || ! empty( $categories ) ) { 
  61. $output = "<select $required name='$name' id='$id' class='$class' $tab_index_attribute>\n"; 
  62. } else { 
  63. $output = ''; 
  64. if ( empty( $categories ) && ! $r['hide_if_empty'] && ! empty( $r['show_option_none'] ) ) { 
  65.  
  66. /** 
  67. * Filters a taxonomy drop-down display element. 
  68. * A variety of taxonomy drop-down display elements can be modified 
  69. * just prior to display via this filter. Filterable arguments include 
  70. * 'show_option_none', 'show_option_all', and various forms of the 
  71. * term name. 
  72. * @since 1.2.0 
  73. * @see wp_dropdown_categories() 
  74. * @param string $element Taxonomy element to list. 
  75. */ 
  76. $show_option_none = apply_filters( 'list_cats', $r['show_option_none'] ); 
  77. $output .= "\t<option value='" . esc_attr( $option_none_value ) . "' selected='selected'>$show_option_none</option>\n"; 
  78.  
  79. if ( ! empty( $categories ) ) { 
  80.  
  81. if ( $r['show_option_all'] ) { 
  82.  
  83. /** This filter is documented in wp-includes/category-template.php */ 
  84. $show_option_all = apply_filters( 'list_cats', $r['show_option_all'] ); 
  85. $selected = ( '0' === strval($r['selected']) ) ? " selected='selected'" : ''; 
  86. $output .= "\t<option value='0'$selected>$show_option_all</option>\n"; 
  87.  
  88. if ( $r['show_option_none'] ) { 
  89.  
  90. /** This filter is documented in wp-includes/category-template.php */ 
  91. $show_option_none = apply_filters( 'list_cats', $r['show_option_none'] ); 
  92. $selected = selected( $option_none_value, $r['selected'], false ); 
  93. $output .= "\t<option value='" . esc_attr( $option_none_value ) . "'$selected>$show_option_none</option>\n"; 
  94.  
  95. if ( $r['hierarchical'] ) { 
  96. $depth = $r['depth']; // Walk the full depth. 
  97. } else { 
  98. $depth = -1; // Flat. 
  99. $output .= walk_category_dropdown_tree( $categories, $depth, $r ); 
  100.  
  101. if ( ! $r['hide_if_empty'] || ! empty( $categories ) ) { 
  102. $output .= "</select>\n"; 
  103. /** 
  104. * Filters the taxonomy drop-down output. 
  105. * @since 2.1.0 
  106. * @param string $output HTML output. 
  107. * @param array $r Arguments used to build the drop-down. 
  108. */ 
  109. $output = apply_filters( 'wp_dropdown_cats', $output, $r ); 
  110.  
  111. if ( $r['echo'] ) { 
  112. echo $output; 
  113. return $output;