wp_list_bookmarks() – Function | Developer.WordPress.org

Retrieves or echoes all of the bookmarks.

Description

List of default arguments are as follows:

These options define how the Category name will appear before the category links are displayed, if ‘categorize’ is 1. If ‘categorize’ is 0, then it will display for only the ‘title_li’ string and only if ‘title_li’ is not empty.

Parameters

$argsstring|arrayoptional

String or array of arguments to list bookmarks.

orderby string
How to order the links by. Accepts post fields. Default 'name'.
order string
Whether to order bookmarks in ascending or descending order.
Accepts 'ASC' (ascending) or 'DESC' (descending). Default 'ASC'.
limit int
Amount of bookmarks to display. Accepts 1+ or -1 for all.
Default -1.
category string
Comma-separated list of category IDs to include links from.
category_name string
Category to retrieve links for by name.
hide_invisible int|bool
Whether to show or hide links marked as 'invisible'. Accepts 1|true or 0|false. Default 1|true.
show_updated int|bool
Whether to display the time the bookmark was last updated.
Accepts 1|true or 0|false. Default 0|false.
echo int|bool
Whether to echo or return the formatted bookmarks. Accepts 1|true (echo) or 0|false (return). Default 1|true.
categorize int|bool
Whether to show links listed by category or in a single column.
Accepts 1|true (by category) or 0|false (one column). Default 1|true.
show_description int|bool
Whether to show the bookmark descriptions. Accepts 1|true or 0|false.
Default 0|false.
title_li string
What to show before the links appear. Default 'Bookmarks'.
title_before string
The HTML or text to prepend to the $title_li string. Default <h2>.
title_after string
The HTML or text to append to the $title_li string. Default </h2>.
class string|array
The CSS class or an array of classes to use for the $title_li.
Default 'linkcat'.
category_before string
The HTML or text to prepend to $title_before if $categorize is true.
String must contain '%id' and '%class' to inherit the category ID and the $class argument used for formatting in themes.
Default <li id="%id" class="%class">.
category_after string
The HTML or text to append to $title_after if $categorize is true.
Default </li>.
category_orderby string
How to order the bookmark category based on term scheme if $categorize is true. Default 'name'.
category_order string
Whether to order categories in ascending or descending order if $categorize is true. Accepts 'ASC' (ascending) or 'DESC' (descending).
Default 'ASC'.

Default:''

Return

void|string Void if 'echo' argument is true, HTML list of bookmarks if 'echo' is false.

Source

function wp_list_bookmarks( $args = '' ) {
	$defaults = array(
		'orderby'          => 'name',
		'order'            => 'ASC',
		'limit'            => -1,
		'category'         => '',
		'exclude_category' => '',
		'category_name'    => '',
		'hide_invisible'   => 1,
		'show_updated'     => 0,
		'echo'             => 1,
		'categorize'       => 1,
		'title_li'         => __( 'Bookmarks' ),
		'title_before'     => '<h2>',
		'title_after'      => '</h2>',
		'category_orderby' => 'name',
		'category_order'   => 'ASC',
		'class'            => 'linkcat',
		'category_before'  => '<li id="%id" class="%class">',
		'category_after'   => '</li>',
	);

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

	$output = '';

	if ( ! is_array( $parsed_args['class'] ) ) {
		$parsed_args['class'] = explode( ' ', $parsed_args['class'] );
	}
	$parsed_args['class'] = array_map( 'sanitize_html_class', $parsed_args['class'] );
	$parsed_args['class'] = trim( implode( ' ', $parsed_args['class'] ) );

	if ( $parsed_args['categorize'] ) {
		$cats = get_terms(
			array(
				'taxonomy'     => 'link_category',
				'name__like'   => $parsed_args['category_name'],
				'include'      => $parsed_args['category'],
				'exclude'      => $parsed_args['exclude_category'],
				'orderby'      => $parsed_args['category_orderby'],
				'order'        => $parsed_args['category_order'],
				'hierarchical' => 0,
			)
		);
		if ( empty( $cats ) ) {
			$parsed_args['categorize'] = false;
		}
	}

	if ( $parsed_args['categorize'] ) {
		// Split the bookmarks into ul's for each category.
		foreach ( (array) $cats as $cat ) {
			$params    = array_merge( $parsed_args, array( 'category' => $cat->term_id ) );
			$bookmarks = get_bookmarks( $params );
			if ( empty( $bookmarks ) ) {
				continue;
			}
			$output .= str_replace(
				array( '%id', '%class' ),
				array( "linkcat-$cat->term_id", $parsed_args['class'] ),
				$parsed_args['category_before']
			);
			/**
			 * Filters the category name.
			 *
			 * @since 2.2.0
			 *
			 * @param string $cat_name The category name.
			 */
			$catname = apply_filters( 'link_category', $cat->name );

			$output .= $parsed_args['title_before'];
			$output .= $catname;
			$output .= $parsed_args['title_after'];
			$output .= "\n\t<ul class='xoxo blogroll'>\n";
			$output .= _walk_bookmarks( $bookmarks, $parsed_args );
			$output .= "\n\t</ul>\n";
			$output .= $parsed_args['category_after'] . "\n";
		}
	} else {
		// Output one single list using title_li for the title.
		$bookmarks = get_bookmarks( $parsed_args );

		if ( ! empty( $bookmarks ) ) {
			if ( ! empty( $parsed_args['title_li'] ) ) {
				$output .= str_replace(
					array( '%id', '%class' ),
					array( 'linkcat-' . $parsed_args['category'], $parsed_args['class'] ),
					$parsed_args['category_before']
				);
				$output .= $parsed_args['title_before'];
				$output .= $parsed_args['title_li'];
				$output .= $parsed_args['title_after'];
				$output .= "\n\t<ul class='xoxo blogroll'>\n";
				$output .= _walk_bookmarks( $bookmarks, $parsed_args );
				$output .= "\n\t</ul>\n";
				$output .= $parsed_args['category_after'] . "\n";
			} else {
				$output .= _walk_bookmarks( $bookmarks, $parsed_args );
			}
		}
	}

	/**
	 * Filters the bookmarks list before it is echoed or returned.
	 *
	 * @since 2.5.0
	 *
	 * @param string $html The HTML list of bookmarks.
	 */
	$html = apply_filters( 'wp_list_bookmarks', $output );

	if ( $parsed_args['echo'] ) {
		echo $html;
	} else {
		return $html;
	}
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘link_category’, string $cat_name ): Filters the category name.
apply_filters( ‘wp_list_bookmarks’, string $html ): Filters the bookmarks list before it is echoed or returned.

Uses	Description
get_terms()`wp-includes/taxonomy.php`	Retrieves the terms in a given taxonomy or list of taxonomies.
_walk_bookmarks()`wp-includes/bookmark-template.php`	The formatted output of a list of bookmarks.
get_bookmarks()`wp-includes/bookmark.php`	Retrieves the list of bookmarks.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
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 more Show less

Used by	Description
wp_get_links()`wp-includes/deprecated.php`	Gets the links associated with category.
wp_get_linksbyname()`wp-includes/deprecated.php`	Gets the links associated with the named category.
WP_Widget_Links::widget()`wp-includes/widgets/class-wp-widget-links.php`	Outputs the content for the current Links widget instance.

Changelog

Version	Description
2.1.0	Introduced.

User Contributed Notes

Skip to note 6 content

Codex 9 years ago

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
Simple List

Displays all bookmarks with the title “Bookmarks” and with items wrapped in tags. The title is wrapped in h2 tags.
```
<?php wp_list_bookmarks('title_li=&category_before=&category_after='); ?>
```
Log in to add feedback
Skip to note 7 content

Codex 9 years ago

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
Simple List without the Heading

Displays all bookmarks as above, but does not include the default heading.
```
<?php wp_list_bookmarks('title_li=&categorize=0'); ?>
```
Log in to add feedback
Skip to note 8 content

Codex 9 years ago

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
Specific Category Sorted by URL

Displays bookmarks for Category ID 2 in span tags, uses images for bookmarks, does not show descriptions, sorts by bookmark URL.
```
<?php wp_list_bookmarks('categorize=0&category=2&before=<span>&after=</span>&show_images=1&show_description=0&orderby=url'); ?>
```
Log in to add feedback
Skip to note 9 content

Codex 9 years ago

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
Shows Ratings and Timestamp

Displays all bookmarks in an ordered list with descriptions on a new line, does not use images for bookmarks, sorts by bookmark id, shows ratings and last-updated timestamp (Note that the last updated timestamp does not track local modifications. It tracks when whatever the link points to is updated via remote requests to pingomatic.)
```
<ol>
<?php wp_list_bookmarks('between=<br />&show_images=0&orderby=id&show_rating=1&show_updated=1'); ?>
</ol>
```
Log in to add feedback
Skip to note 10 content

Codex 9 years ago

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
Replaces Heading with Image

Uses an image from the theme folder instead of plain text.
```
<?php wp_list_bookmarks('categorize=0&title_before=&title_after=&title_li=<img src="'.get_bloginfo("stylesheet_directory").'/images/blogroll.gif" alt="blogroll" />'); ?>
```
Log in to add feedback

wp_list_bookmarks( string|array $args = ” ): void|string

In this article