Update pagination component to add new numbered pages variant

[frankieroberto]

This updates Pagination component to support a new variant which is suitable for paging between numbered lists of pages, for example in search results or a long list of patients or appointments.

The variant is based on the GOV.UK Pagination variant, but with a few changes to match NHS styling, and some differences in the macro params.

The component is backwards-compatible, so the existing previous and next pagination variant is unchanged.

TODO

• Mobile view
• Write guidance
• Test in all supported browsers
• Unit tests
• Add to backstop image tests
• Code review
• CHANGELOG entry

[paulrobertlloyd]

The existing Previous and Next variant for the NHS pagination component uses different HTML from the GOV.UK one, for example the NHS one uses a <ul> list containing 1 or 2 list items, whereas the GOV.UK one uses <div>s.

Is there an opportunity for us to follow the GOV.UK decision here? My spidey sense is that using a list item for the now and next page items, inside a navigation landmark labelled pagination, is misleading (there may be more than 2 pages, its just that only the previous and next ones have been linked to).

Further more, if you have numbered pagination with say 3 items, it’ll be announced in a list having 5 items. Which is to say, I think the distinction between those links that appear in a list, and those used for previous and next links, is an important one.

To avoid making any breaking changes to the existing pagination component, I’ve left that as-is, including all the existing HTML and CSS classes.

How compatible with the GOV.UK markup would this component be, say if you were using – entirely hypothetically you understand – a GOV.UK-based component library that allowed you to use NHS styles by changing class prefixes from govuk-* to nhsuk-* (cough)?

---

Separately, see #1027; from both wanting visual consistency, and being able to identify the pagination arrows at these smaller sizes, the existing pagination arrows should have open tips.

[frankieroberto]

@paulrobertlloyd:

Is there an opportunity for us to follow the GOV.UK decision here? My spidey sense is that using a list item for the now and next page items, inside a navigation landmark labelled pagination, is misleading (there may be more than 2 pages, its just that only the previous and next ones have been linked to).

Further more, if you have numbered pagination with say 3 items, it’ll be announced in a list having 5 items. Which is to say, I think the distinction between those links that appear in a list, and those used for previous and next links, is an important one.

Ah sorry, I didn’t explain this well enough. I’ve followed the GOVUK markup for the new 'numbered pages' variant. This means that the numbers are within a <ul> list, but the previous and next links are in a separate <div> before or after the list, and not part of the list.

What I’ve not done is changed the markup used for the existing 'previous and next links with page titles' variant, which uses this markup in the NHS version:

<nav><ul>
  <li><a href="#">Previous: page title</a></li>
  <li><a href="#">Next: page title</a></li>
</ul></nav>

but this in the GOV.UK version:

<nav>
  <a href="#">Previous: page title</a>
  <a href="#">Next: page title</a>
</nav>

(<div>s and <span>s not shown)

Possibly we should also update this to match the GOV.UK version, but possibly the <ul> list is beneficial here (or not?) - and I also wanted to avoid a breaking change, at least initially. But maybe it’s better to do that at the same time?

How compatible with the GOV.UK markup would this component be, say if you were using – entirely hypothetically you understand – a GOV.UK-based component library that allowed you to use NHS styles by changing class prefixes from govuk-* to nhsuk-* (cough)?

Right now the markup for the new numbered pages variant should be mostly compatible except for the SVG for the arrows, which is different. There might also be some other differences in the css names.

[paulrobertlloyd]

But maybe it’s better to do that at the same time?

Do it

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Arpana18]

How can we hide (not show) the 'Previous' link when users are on the first page AND "Next" link when users are on the last page?

Our user research revealed that participants were confused about what the 'Previous' link would do when they're already on page 1. Similarly, users expect the 'Next' link to be disabled when they reach the last page.

This feedback suggests we need to implement hide states for pagination controls to provide clearer visual cues about available navigation options.

[frankieroberto]

How can we hide (not show) the 'Previous' link when users are on the first page AND "Next" link when users are on the last page?

@Arpana18 Hiya - the previous and next links are only shown when specified in the HTML or in the previous and next params within the Nunjucks macro. We’ll make it clearer in the accompanying guidance how to do this! Thanks for commenting. 👍

[frankieroberto]

@colinrotherham @paulrobertlloyd I've updated this from main and fixed the conflicts and deprecations (I think).

Next step is to sort out the mobile view. Follow GOVUK and go centre aligned, with 'Previous' stacked above the numbers and 'Next' stacked below?

[colinrotherham]

Next step is to sort out the mobile view. Follow GOVUK and go centre aligned, with 'Previous' stacked above the numbers and 'Next' stacked below?

I'd say so, but only in the absence of a better (researched) option.

For comparison we could look at ideas in:

• Pagination component numbering issue on small screens alphagov/govuk-frontend#3324
• [SPIKE] Modifications to pagination component alphagov/govuk-frontend#3644

[colinrotherham]

Sorry about the force push @frankieroberto

I've removed all the link style overrides so the defaults are now used, including :visited etc

Would be good to chat about the --block modifier used by GOV.UK Frontend

A few of the default styles were causing conflicts without it (e.g. stretching link :hover over the whole item)

[colinrotherham]

Sorry about the force push again, 639 commits added and macro options are now ES modules

[colinrotherham]

Merged with latest main now review app examples are consolidated

[frankieroberto]

@colinrotherham I'm planning to pick this up again later this week, as it a component desperately needed by my service.

But this would be a v11 thing.

[colinrotherham]

Updated with main where reference images were generated again

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[colinrotherham]

Fixed all the conflicts to bring in:

1. Next and Previous icons via nhsukIcon()
2. Link colours from Change link hover and active colours #1367
3. Link underlines from Add link underline offset and make underline thicker on hover #1366

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[frankieroberto]

Okay I’ve updated this, with the main aim of making this now backwards-compatible, so that it is no longer a breaking change.

The downside of this is that it remains un-aligned with the govuk frontend one at both the macro level and the HTML output is also slightly different (especially for the existing variant), but I’ve made it as compatible as I can. The use of the nested nhsukIcon macro means it’ll never be 100% the same anyway.

We could still decide to deprecate previousUrl for previous.href and previousText for previous.labelText etc, if we wanted to.

Still got a bit of fiddling to do on the design and the mobile-responsiveness, but getting closer...

[colinrotherham]

Have a look from line 6?

https://github.com/nhsuk/nhsuk-frontend/blob/component-form-inputs/packages/nhsuk-frontend/src/nhsuk/components/input/template.njk

I had to do some wrangling to make the GOV.UK Frontend object syntax for prefix/suffix work with our strings

But it worked. Old and new API,
side by side

If that opens any doorways for you?

[frankieroberto]

@colinrotherham yeah, I was considering doing similar to support both previousUrl (which could be deprecated) and previous.href. Depends how important we think it is to update the Nunjucks params.

For now, I’ll focus on the remaining design tasks.