8.5.x pager.inc pager_default_initialize($total, $limit, $element = 0)
8.0.x pager.inc pager_default_initialize($total, $limit, $element = 0)
8.1.x pager.inc pager_default_initialize($total, $limit, $element = 0)
8.2.x pager.inc pager_default_initialize($total, $limit, $element = 0)
8.3.x pager.inc pager_default_initialize($total, $limit, $element = 0)
8.4.x pager.inc pager_default_initialize($total, $limit, $element = 0)
8.6.x pager.inc pager_default_initialize($total, $limit, $element = 0)
7.x pager.inc pager_default_initialize($total, $limit, $element = 0)

Initializes a pager for theme('pager').

This function sets up the necessary global variables so that future calls to theme('pager') will render a pager that correctly corresponds to the items being displayed.

If the items being displayed result from a database query performed using Drupal's database API, and if you have control over the construction of the database query, you do not need to call this function directly; instead, you can simply extend the query object with the 'PagerDefault' extender before executing it. For example:

$query = db_select('some_table')

However, if you are using a different method for generating the items to be paged through, then you should call this function in preparation.

The following example shows how this function can be used in a page callback that invokes an external datastore with an SQL-like syntax:

// First find the total number of items and initialize the pager.
$where = "status = 1";
$total = mymodule_select("SELECT COUNT(*) FROM data " . $where)
$num_per_page = variable_get('mymodule_num_per_page', 10);
$page = pager_default_initialize($total, $num_per_page);

// Next, retrieve and display the items for the current page.
$offset = $num_per_page * $page;
$result = mymodule_select("SELECT * FROM data " . $where . " LIMIT %d, %d", $offset, $num_per_page)
$output = theme('mymodule_results', array(
  'result' => $result,

// Finally, display the pager controls, and return.
$output .= theme('pager');
return $output;

A second example involves a page callback that invokes an external search service where the total number of matching results is provided as part of the returned set (so that we do not need a separate query in order to obtain this information). Here, we call pager_find_page() to calculate the desired offset before the search is invoked:

// Perform the query, using the requested offset from pager_find_page().
// This comes from a URL parameter, so here we are assuming that the URL
// parameter corresponds to an actual page of results that will exist
// within the set.
$page = pager_find_page();
$num_per_page = variable_get('mymodule_num_per_page', 10);
$offset = $num_per_page * $page;
$result = mymodule_remote_search($keywords, $offset, $num_per_page);

// Now that we have the total number of results, initialize the pager.
pager_default_initialize($result->total, $num_per_page);

// Display the search results.
$output = theme('search_results', array(
  'results' => $result->data,
  'type' => 'remote',

// Finally, display the pager controls, and return.
$output .= theme('pager');
return $output;


$total: The total number of items to be paged.

$limit: The number of items the calling code will display per page.

$element: An optional integer to distinguish between multiple pagers on one page.

Return value

The number of the current page, within the pager represented by $element. This is determined from the URL query parameter $_GET['page'], or 0 by default. However, if a page that does not correspond to the actual range of the result set was requested, this function will return the closest page actually within the result set.

2 calls to pager_default_initialize()
EntityFieldQuery::initializePager in includes/entity.inc
Gets the total number of results and initializes a pager for the query.
PagerDefault::execute in includes/pager.inc
Override the execute method.


includes/pager.inc, line 274
Functions to aid in presenting database results as a set of pages.


function pager_default_initialize($total, $limit, $element = 0) {
  global $pager_page_array, $pager_total, $pager_total_items, $pager_limits;
  $page = pager_find_page($element);

  // We calculate the total of pages as ceil(items / limit).
  $pager_total_items[$element] = $total;
  $pager_total[$element] = ceil($pager_total_items[$element] / $limit);
  $pager_page_array[$element] = max(0, min($page, (int) $pager_total[$element] - 1));
  $pager_limits[$element] = $limit;
  return $pager_page_array[$element];


MXT’s picture

Can you please provide an example to obtain pagination with an array as source?

For example:

$tree = taxonomy_get_tree($vid)

how to split the resulting $tree array in more pages?

Thank you very much.

tobyontour’s picture

Quick and dirty example:

// $list is the list of items you are paging through
$list = array ('Cat','Dog','Mouse','Horse','Pony','Winged mongoose');
$per_page = 2;

// Initialise the pager
$current_page = pager_default_initialize(count($list), $per_page);

// Split your list into page sized chunks
$chunks = array_chunk($list,$per_page, TRUE);

// Show the pager
print theme('pager', array('quantity',count($list)));

// Show the appropriate items from the list
print theme('item_list', array(
   'items' => $chunks[$current_page],

hdog’s picture

Nice example. It worked for me. Tried it with a mulit-dimensional array. It paginates but each page only has the list item bullet. How would I go about fixing this?


edutrul’s picture

This example, works awesome!

I used EntityQuery plus a lot of filter of data because of business logic.

And your example saved me!

pranavpathak’s picture

Thanks a lot :-)

Shiraz Dindar’s picture

this was the only place i could find how to programmatically add a pager for own content

deepakgl881@gmail.com’s picture

Very usefull

AleksandrErmakov’s picture

I can`t simply extend the query object with the 'PagerDefault'!
This code not work in hook_block_view
$query = db_select('some_table')->extend('PagerDefault');
theme('pager') always null.

Pager work in hook_block_view only if I use pager_default_initialize before theme('pager').
Therefore i use next code

$page = pager_find_page()+1;
$total = 3;
	// Drupal 7, вариант 2 (более правильный)
	$nodes = db_select('node', 'n')
  ->range(($page-1) * $total, $total)
  ->condition('n.nid', $nids, 'IN');
	$nodes->leftJoin('field_data_body', 'fulln', 'n.nid = fulln.entity_id');
	$res = $nodes->execute();
	$valdb = array();
	$content = '<article>';
	$rc = rowcount($nids);
	$total = ceil($rc / $total);
	foreach ($res as $item) {
	$content .= '<article>

	<div class="articleconteiner">


<a href="[[~[[+id]]]]" title="'.$item->title.'"><div class="calendar" style="float:left;">
	<div class="calendartop">
	'. format_date($item->created, 'custom','Y').'
	<div class="calendarcenter">
	'. format_date($item->created, 'custom','d').'
	<div class="calendarbottom">
	'.rus_date(format_date($item->created, 'custom','M')).'


	<h2 class="header"><a href="o-srednej-prodolzhitelnosti-zhizni-v-rossii-v-raznyie-periodyi-istorii.html"><span style="color:#38AA00 !important;">'.$item->title.'</span></a></h2>

	pager_default_initialize($total, 1, $element = 0);
	$content .= theme('pager');
	$block['content'] =  $content;

Is that right? Thank you!

James Nesbitt’s picture

If you are using Drupal pager with a data backend that has no separation between count query, and data query, such that you need to know that page number, without knowing yet the total count, then you cannot use this function.

Look instead at https://api.drupal.org/api/drupal/includes%21pager.inc/function/pager_fi...

@note that this alternate function does not correct your page number if you have a requested an invalid page.

An example might be a data retrieval backend where you pass in the page number, but it gives you both the page data, and a total count. Many RPC services work this way.