WordPress.org

Ready to get started?Download WordPress

Codex

Function Reference/wp category checklist

Contents

Description

Output an unordered list of checkbox <input> elements labeled with category names. This is essentially a convenience function for simplifying calls to wp_terms_checklist()

Usage

<?php
   wp_category_checklist
$post_id$descendants_and_self$selected_cats,
         
$popular_cats$walker$checked_ontop);
?>

Parameters

While strictly speaking all parameters are optional because there are defaults, this function is not so useful without specifying either a $post_id or an array of $selected_cats. But don't try to do both.

$post_id
(integer) (optional) Mark categories associated with this post as checked. $selected_cats must be false, and not an array, if a nonzero value is passed here.
Default: 0
$descendants_and_self
(integer) (optional) ID of the category to output along with its descendents.
Default: 0
$selected_cats
(boolean|array) (optional) An array of category IDs to mark as checked. If passing a valid $post_id, this should be set as false.
Default: false
$popular_cats
(boolean|array) (optional) An array of category IDs that overrides the list of categories receiving the "popular-category" class.
Default: false
$walker
(object) (optional) Walker object to use to build the output. If empty, an instance of Walker_Category_Checklist will be used.
Default: null
$checked_ontop
(boolean) (optional) Move checked items out of the hierarchy and to the top of the list.
Default: true

Examples

Output a list off all categories:

wp_category_checklist();

Output a the list of a certain category and its descendants:

$category_id = 22;

wp_category_checklist( 0, $category_id );

Mark all categories for a particular post as checked:

$post_id = 45;

wp_category_checklist( $post_id );

Specify an array of categories to preselect instead:

$selected_cats = array( 45, 33, 118 );

wp_category_checklist( 0, 0, $selected_cats );

To override which categories will be marked as popular:

$popular = array( 45, 33, 118 );

wp_category_checklist( 0, 0, false, $popular );

Specify a walker object to use:

$walker = new My_Walker_Category_Checklist;

wp_category_checklist( 0, 0, false, false, $walker );

List the checked categories before the rest:

$selected_cats = array( 45, 33, 118 );
$checked_ontop = true;

wp_category_checklist( 0, 0, $selected_cats, false, null, $checked_ontop );

You may also use any of the parameters in combination, except for $post_id and $selected_cats, which should not be used together.

Changelog

Since 2.5.1

Source File

wp_category_checklist() is located in wp-admin/includes/template.php.

Related

List & Dropdown Functions

See also index of Function Reference and index of Template Tags.