Sort

Examples

Medications

Mobile

Desktop

Questions

Find a Form

Secure Messaging

Usage

When to use Sort

• When there are clear, meaningful ways to sort. Sort options should help users achieve their goals. Common contexts include:
  • Search results
  • Medications
  • Appointments
  • Secure messages
  • Claims
  • History
• When there is more than one page of results or more than 10 items.

When to consider something else

• When the order of data doesn’t affect the results or how users understand them.
• When there’s only one obvious order. You need at least two sort options to use this component.
• When you want to narrow results down. Use a Filter instead.
  • For example, don’t use Sort to filter by date ranges.
• When sorting within a table, use the sort columns baked into the va-table component.

Behavior

Web

• User clicks the dropdown to open a list of sort options. Alternatively, a screen-reader user may arrow up and down the list without opening the menu. The Sort component uses the Select as the foundation and shares similar behavior.

• Results automatically update when you select a sort option. This is known as implicit submission.
  • Why implicit submission?
    • Using a button to confirm a sort choice (explicit submission) was found to be easily missed. A 2024 VA.gov Medications Round 3 study mentions:

      “6 of 11 participants missed the Sort button after selecting the sort option. Vision did not seem to play a role in who missed the button as 4 of the 6 were sighted. One screen reader dependent user did mention missing things because of his speed.”

    • The Design Systems Council met with multiple product teams and accessibility specialists to align on implicit submission (supplemented with important accessibility considerations) as the expected behavior.

• Sort applies to the entire data set, not just the current page. When you sort, the paginated results reset to page 1.

• Sort selections persist across interactions. The sort criteria should remain when users navigate through paginated results or refresh the page.

• Sizing and alignment differ on mobile and desktop.
  • On desktop resolutions, the width is fixed and the Sort by label is in line with the dropdown.
    • Choose Medium (md), Large (lg), or Extra Large (xl) size, whichever prevents truncating the longest sort option.
  • On mobile resolutions, the component is full-width and responsive. The Sort by label is stacked on top of the dropdown.

Placement

• Place Sort above and aligned with the content that it affects. It serves as a visual indicator of the current order.
• If used with the Search Filter, place Sort after the Search Filter’s results description. This prevents the focus from skipping the Sort component given that the focus for filtering moves to results description or results heading and the focus for sorting is maintained on the component.

Mobile app

• The VA mobile app does not currently use this component. It uses its own combined Filter & Sort button that opens a modal to select and explicitly submit sort and filter options.
  • 
• The naming of sort options must still remain consistent across mobile and desktop experiences.

Code usage

• Relying on an API to sort and paginate data is permissible. If sorting data on the frontend is more efficient, remember to format times and dates in a way that will ensure a correct chronological sort.
  • Store date and time as an ISO-formatted string (date and time in UTC or date and time with offset).
    • Attempting to sort dates as strings like 2/20/2025, 10/1/2024, 9/5/2023 from newest to oldest, for example, could result in a non-chronological A-Z sort:
      • 10/1/2024
      • 2/20/2025
      • 9/5/2023
    • A true chronological sort by year, month, then day would instead be:
      • 2/20/2025
      • 10/1/2024
      • 9/5/2023

Content considerations

Content expectations

• Provide a default sort option that reflects what users expect in the given context. In search experiences, Relevance is often the default.
  • Don’t present a placeholder option (such as - Select -) as a selectable sort choice.
• Name sort options clearly and consistently so users understand both what is being sorted and how it’s ordered.
  • Use this convention: [Sort attribute] (sort method)
    • [Sort attribute] describes what the results are sorted by (for example, medication name, entry date, or distance).
    • (Sort method) describes the ordering. Use familiar, plain language terms such as:
      • Alphabetical
        • A to Z
      • Chronological
        • Newest to oldest
      • Numerical
        • Least to most
        • Closest to furthest
        • Smallest to largest
        • Lowest to highest
        • Shortest to longest
  • Note: Avoid offering a sort method on its own without clearly identifying the attribute being sorted.
    • For example, if a Vaccine history card only shows a date value, use a label like Date received (newest to oldest) rather than Newest to oldest.
  • Examples of clear and consistent sort option labels include:
    • Medication name (A to Z)
    • Date entered (newest to oldest)
    • Refills remaining (least to most)
    • Distance (closest to furthest)
  • Keep sort option labels consistent across mobile and desktop. For example, if mobile uses Date filled (newest to oldest), desktop should use the same wording—not something different like Fill date (newest to oldest).

Additional guidance

• Consider allowing users to sort in both directions—for example, A to Z and Z to A.
  • Offering both directions isn’t necessary when the reverse order wouldn’t be meaningful or useful for users’ goals. For example, it may not make sense to sort VA locations from furthest to closest.

• Only include sort options that provide clear value. The ability to sort data doesn’t automatically mean it will help users.

• Sort does not need to be reflected in the results description for web and mobile. The component already acts as a visual indicator of the order. However, it is required for the mobile app since the sort state is hidden within the modal.

Accessibility considerations

These considerations describe how sorting changes are communicated and experienced by users of assistive technologies.

User experience expectations

• When a sort option is selected, users need to be informed that the results have updated. This is especially important for screen reader users who may not see the visual change.
• Sorted results should update in a meaningful and predictable order so all users perceive the same sequence of information (WCAG 1.3.2 Meaningful Sequence).
• Sorting updates the results in place and does not trigger page navigation or a full context change.
• Focus remains stable on the sort control during sorting so users can continue interacting without losing their place.
• If sorting takes time, inform users that an update is in progress by following the loading indicator guidance.

Implementation notes

• Announce sorting changes in a non-disruptive way using aria-live="polite" so assistive technology users understand that results have changed without interrupting their workflow.
• Account for assistive technology interaction patterns where users may move through select options without opening the menu. Avoid triggering unnecessary updates while a user is exploring options. Engineers should debounce network requests or delay the vaSortSelect or vaSortKeyDown events to check for another option selection.
• Optgroups aren’t supported in the va-sort component.

Related

• Select
• Search Input
• Search Filter
• Search Results
• USWDS Table Component

Provide feedback

Share your feedback, report issues, or suggest improvements for the Sort component. Your input helps us make the design system better for everyone.

• Get immediate support in #platform-design-system for technical or urgent issues.
• Explore all feedback channels for additional ways to share your input.