Pagination Nunjucks macro options

Use options to customise the appearance, content and behaviour of this component when using a macro, for example, changing the text.

Also see the guidance on the Pagination component page, which shows these options in use within each example.

Some options are required for the macro to work; these are marked as "Required" in the option description. Deprecated options are marked as "Deprecated".

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Primary options
Name Type Description
items array The items within the pagination component. See macro options for items.
previous object A link to the previous page, if there is a previous page. See macro options for previous.
next object A link to the next page, if there is a next page. See macro options for next.
landmarkLabel string The label for the navigation landmark that wraps the pagination. Defaults to "Pagination".
classes string The classes you want to add to the pagination nav parent.
attributes object The HTML attributes (for example, data attributes) you want to add to the pagination nav parent.
Options for items array objects
Name Type Description
number string The pagination item text – usually a page number. Required unless the item is an ellipsis.
visuallyHiddenText string The visually hidden label for the pagination item, which will be applied to an aria-label and announced by screen readers on the pagination item link. Should include page number. Defaults to, for example “Page 1”.
href string The link’s URL. Required unless the item is an ellipsis.
current boolean Set to true to indicate the current page the user is on.
ellipsis boolean Use this option if you want to specify an ellipsis at a given point between numbers. If you set this option as true, any other options for the item are ignored.
attributes object The HTML attributes (for example, data attributes) you want to add to the anchor.
Options for previous object
Name Type Description
text string The text content of the link to the previous page. Defaults to "Previous page", with ‘page’ being visually hidden. If html is provided, the text option will be ignored.
html string The HTML content of the link to the previous page. Defaults to "Previous page", with ‘page’ being visually hidden. If html is provided, the text option will be ignored.
labelText string The optional label that goes underneath the link to the previous page, providing further context for the user about where the link goes.
href string Required. The previous page’s URL.
attributes object The HTML attributes (for example, data attributes) you want to add to the anchor.
Options for next object
Name Type Description
text string The text content of the link to the next page. Defaults to "Next page", with ‘page’ being visually hidden. If html is provided, the text option will be ignored.
html string The HTML content of the link to the next page. Defaults to "Next page", with ‘page’ being visually hidden. If html is provided, the text option will be ignored.
labelText string The optional label that goes underneath the link to the next page, providing further context for the user about where the link goes.
href string Required. The next page’s URL.
attributes object The HTML attributes (for example, data attributes) you want to add to the anchor.