pageNumberLinks()

Signature

pageNumberLinks() — returns string

Available in: controller Category: Pagination Functions

Description

Creates a windowed set of page number links around the current page. The current page is rendered as a span (not a link) unless linkToCurrentPage is true.

When non-plain, emits the canonical wrapper markup for that framework (e.g.

) and ignores prependToPage / appendToPage / classForCurrent / class in favor of the preset.

Parameters

Name	Type	Required	Default	Description
windowSize	numeric	no	2	The number of page links to show around the current page.
handle	string	no	query	The handle given to the query that the pagination should be displayed for.
name	string	no	page	The name of the param that holds the current page number.
class	string	no	—	CSS class for each page number link.
classForCurrent	string	no	current	CSS class for the current page span or link.
linkToCurrentPage	boolean	no	false	Whether to render the current page as a link.
prependToPage	string	no	—	String to prepend before each page number.
appendToPage	string	no	—	String to append after each page number.
addActiveClassToPrependedParent	boolean	no	false	Whether to inject active into the prependToPage class attribute on the current page (Bootstrap idiom). Has no effect if prependToPage contains no class attribute.
pageNumberAsParam	boolean	no	true	Decides whether to link the page number as a param or as part of a route.
viewStyle	string	no	plain	CSS-framework preset for markup: “plain” (default), “bootstrap5”, “bootstrap4”, or “tailwind”.
encode	any	no	true	Use this argument to decide whether the output of the function should be encoded in order to prevent Cross Site Scripting (XSS) attacks. Set it to true to encode all relevant output for the specific HTML element in question (e.g. tag content, attribute values, and URLs). For HTML elements that have both tag content and attribute values you can set this argument to attributes to only encode attribute values and not tag content.

Examples

//--------------------------------------------------------------------
// Example 1: Basic page number links for a paginated query

// Controller code
param name="params.page" type="integer" default="1";
posts = model("Post").findAll(page=params.page, perPage=10, order="createdAt DESC");

// View code — renders links like: 1 2 [3] 4 5  (current page as a span)
<cfoutput>#pageNumberLinks()#</cfoutput>


//--------------------------------------------------------------------
// Example 2: Widen the window around the current page and add CSS classes

// View code — shows 5 pages on each side of the current page,
// styling each link and the current-page span differently
<cfoutput>
    #pageNumberLinks(windowSize=5, class="page-link", classForCurrent="active")#
</cfoutput>


//--------------------------------------------------------------------
// Example 3: Wrap each page number in a list item

// View code
<ul>
    <cfoutput>
        #pageNumberLinks(prependToPage="<li>", appendToPage="</li>")#
    </cfoutput>
</ul>


//--------------------------------------------------------------------
// Example 4: Make the current page a link (useful for reloading)

// View code
<cfoutput>#pageNumberLinks(linkToCurrentPage=true)#</cfoutput>


//--------------------------------------------------------------------
// Example 5: Multiple paginated queries — reference each by its handle

// Controller code
authors = model("Author").findAll(handle="authorQuery", page=params.page, perPage=20, order="lastName");
posts   = model("Post").findAll(handle="postQuery",   page=params.page, perPage=5,  order="createdAt");

// View code
<cfoutput>
    Authors: #pageNumberLinks(handle="authorQuery")#
    Posts:   #pageNumberLinks(handle="postQuery")#
</cfoutput>