wp_terms_checklist() │ WP 3.0.0

Displays/retrieve the UL list of checkbox input elements input type="checkbox" labelled with term names.

Taxonomy-independent version of wp_category_checklist().

To work on the front-end, you need to connect the file:

require_once ABSPATH .'/wp-admin/includes/template.php';
1 time — 0.000455 sec (fast) | 50000 times — 10.85 sec (slow)
Hooks from the function

Returns

String. If echo argument is set to true, displays HTML code, otherwise returns the HTML.

Usage pattern

wp_terms_checklist( $post_id, [
	'descendants_and_self' => 0,
	'selected_cats'        => false,
	'popular_cats'         => false,
	//'walker'               => null,
	'taxonomy'             => 'category',
	'checked_ontop'        => true,
	'echo'                 => true,
] );

Usage

wp_terms_checklist( $post_id, $args );
$post_id(int)
Post ID.
$args(array|string)

Array or string of arguments for generating a terms checklist.

Default: empty array

  • descendants_and_self(int)
    ID of the category to output along with its descendants.

  • selected_cats(int[])
    Array of category IDs to mark as checked.
    Default: false

  • popular_cats(int[])
    Array of category IDs to receive the "popular-category" class.
    Default: false

  • walker(Walker)
    Walker object to use to build the output.
    Default: empty which results in a Walker_Category_Checklist instance being used

  • taxonomy(string)
    Taxonomy to generate the checklist for.
    Default: 'category'

  • checked_ontop(true|false)
    Whether to move checked items out of the hierarchy and to the top of the list.
    Default: true

  • echo(true|false)
    Whether to echo the generated markup. False to return the markup instead of echoing it.
    Default: true

Examples

0

#1 Get the checklist of taxonomy elements

Let's say we have taxonomy wpfunc and we need to list the checkboxes of element 51 and all its children elements. Also, specify dedicated and popular items.

require_once ABSPATH .'/wp-admin/includes/template.php';

$args = [
	'descendants_and_self' => 51,
	'selected_cats'        => array(219, 52),
	'popular_cats'         => array(219, 52),
	'taxonomy'             => 'wpfunc',
	'checked_ontop'        => true
];

echo '<ul>';
wp_terms_checklist( 0, $args );
echo '</ul>';

Displays:

<ul>
	<li id='wpfunc-52' class="popular-category">
		<label class="selectit"><input value="52" type="checkbox" name="tax_input[wpfunc][]" id="in-wpfunc-52" checked='checked' /> Comments</label>
	</li>

	<li id='wpfunc-219' class="popular-category">
		<label class="selectit"><input value="219" type="checkbox" name="tax_input[wpfunc][]" id="in-wpfunc-219" checked='checked' /> Comment pagination</label>
	</li>

	<li id='wpfunc-51'>
		<label class="selectit"><input value="51" type="checkbox" name="tax_input[wpfunc][]" id="in-wpfunc-51" /> Comments, Pings...</label>
		<ul class='children'>
			<li id='wpfunc-218'>
				<label class="selectit"><input value="218" type="checkbox" name="tax_input[wpfunc][]" id="in-wpfunc-218" /> Comments Loop</label>
			</li>
		</ul>
	</li>
</ul>

Changelog

Since 3.0.0 Introduced.
Since 4.4.0 Introduced the $echo argument.

wp_terms_checklist() code WP 6.8.3

wp-admin/includes/template.php 
function wp_terms_checklist( $post_id = 0, $args = array() ) {
	$defaults = array(
		'descendants_and_self' => 0,
		'selected_cats'        => false,
		'popular_cats'         => false,
		'walker'               => null,
		'taxonomy'             => 'category',
		'checked_ontop'        => true,
		'echo'                 => true,
	);

	/**
	 * Filters the taxonomy terms checklist arguments.
	 *
	 * @since 3.4.0
	 *
	 * @see wp_terms_checklist()
	 *
	 * @param array|string $args    An array or string of arguments.
	 * @param int          $post_id The post ID.
	 */
	$params = apply_filters( 'wp_terms_checklist_args', $args, $post_id );

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

	if ( empty( $parsed_args['walker'] ) || ! ( $parsed_args['walker'] instanceof Walker ) ) {
		$walker = new Walker_Category_Checklist();
	} else {
		$walker = $parsed_args['walker'];
	}

	$taxonomy             = $parsed_args['taxonomy'];
	$descendants_and_self = (int) $parsed_args['descendants_and_self'];

	$args = array( 'taxonomy' => $taxonomy );

	$tax              = get_taxonomy( $taxonomy );
	$args['disabled'] = ! current_user_can( $tax->cap->assign_terms );

	$args['list_only'] = ! empty( $parsed_args['list_only'] );

	if ( is_array( $parsed_args['selected_cats'] ) ) {
		$args['selected_cats'] = array_map( 'intval', $parsed_args['selected_cats'] );
	} elseif ( $post_id ) {
		$args['selected_cats'] = wp_get_object_terms( $post_id, $taxonomy, array_merge( $args, array( 'fields' => 'ids' ) ) );
	} else {
		$args['selected_cats'] = array();
	}

	if ( is_array( $parsed_args['popular_cats'] ) ) {
		$args['popular_cats'] = array_map( 'intval', $parsed_args['popular_cats'] );
	} else {
		$args['popular_cats'] = get_terms(
			array(
				'taxonomy'     => $taxonomy,
				'fields'       => 'ids',
				'orderby'      => 'count',
				'order'        => 'DESC',
				'number'       => 10,
				'hierarchical' => false,
			)
		);
	}

	if ( $descendants_and_self ) {
		$categories = (array) get_terms(
			array(
				'taxonomy'     => $taxonomy,
				'child_of'     => $descendants_and_self,
				'hierarchical' => 0,
				'hide_empty'   => 0,
			)
		);
		$self       = get_term( $descendants_and_self, $taxonomy );
		array_unshift( $categories, $self );
	} else {
		$categories = (array) get_terms(
			array(
				'taxonomy' => $taxonomy,
				'get'      => 'all',
			)
		);
	}

	$output = '';

	if ( $parsed_args['checked_ontop'] ) {
		/*
		 * Post-process $categories rather than adding an exclude to the get_terms() query
		 * to keep the query the same across all posts (for any query cache).
		 */
		$checked_categories = array();
		$keys               = array_keys( $categories );

		foreach ( $keys as $k ) {
			if ( in_array( $categories[ $k ]->term_id, $args['selected_cats'], true ) ) {
				$checked_categories[] = $categories[ $k ];
				unset( $categories[ $k ] );
			}
		}

		// Put checked categories on top.
		$output .= $walker->walk( $checked_categories, 0, $args );
	}
	// Then the rest of them.
	$output .= $walker->walk( $categories, 0, $args );

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

	return $output;
}

List (wp_list)

Taxonomies (Categories, Tags)