HDS Pagination - Auto-Switch to Simplified

[abbybowman]

Feature name

HDS Pagination: auto-switch to simplified on small screens

Feature area

Component patterns (cards, search, archive layouts, etc.)

Describe the idea

HDS pagination ships with three variants: bounded (numbered, known total), unbounded (numbered, unknown total), and simplified (Previous/Next text buttons only). Currently, developers choose which variant to render. This idea adds a CSS-only responsive pattern that automatically switches from a numbered variant to simplified on small viewports.

Both markup variants would need to be present in the DOM, with CSS media queries toggling visibility:

<nav class="usa-pagination" aria-label="Pagination">
  <!-- Numbered — hidden on small screens -->
  <ul class="usa-pagination__list usa-pagination__list--full">
    ...page numbers...
  </ul>
  <!-- Simplified — hidden on large screens, shown on small -->
  <ul class="usa-pagination__list usa-pagination__list--simplified">
    ...prev/next only...
  </ul>
</nav>

This fits HDS Core's CSS-only approach — no JavaScript needed.

Use case / user story

As a developer, I want pagination to automatically adapt to mobile viewports so that I don't need to implement viewport detection logic or serve different markup per breakpoint.

Primary audience

Front-end developers

Is this already in the HDS Figma library?

🟡 Partially — some elements exist but not complete

Figma reference

The HDS Figma Pagination page shows simplified pagination annotated "For mobile pagination" but doesn't include explicit responsive breakpoint specs.

Implementation maturity

🔍 Seen elsewhere — exists in another design system or library (not NASA)

Prior art details

Not sure if responsive pagination switching has been implemented on NASA.gov or any live NASA sites. Some design systems (e.g., Carbon, Spectrum) handle this at the JS framework level rather than pure CSS.

Relationship to USWDS

Extends USWDS with something it doesn't provide

Potential breaking change?

No — purely additive

Alternatives considered

1. JavaScript-based switching — detect viewport and render only one variant. More DOM-efficient but requires JS, which HDS Core doesn't currently ship.
2. Developer responsibility — current approach. Document the pattern and let developers implement responsive switching in their framework. Simpler for HDS Core but inconsistent across implementations.
3. CSS container queries — switch based on pagination container width rather than viewport. More flexible but browser support may be a concern -- need to check against our targeted browsers.

Additional context

• The numbered and simplified variants use different markup structures (simplified uses .hds-pagination__simplified-btn composed buttons), so this can't be done with CSS alone on a single markup tree — both need to be in the DOM
• Accessibility consideration: the hidden variant should use display: none (not visibility: hidden) so screen readers don't encounter duplicate navigation
• USWDS has the $theme-pagination-breakpoint setting which controls when full pagination displays — this could potentially be leveraged

Would you contribute to this?

Partially — I could help with design/research/testing