Sort

Examples

Default

View va-sort default in Storybook

Custom Default Value

View va-sort–custom-default-value in Storybook

Widths

View va-sort–widths in Storybook

Mockups

Medications (Mobile)

Medications (Desktop)

Questions

Find a Form

Secure Messaging

Usage

When to use Sort

• When there are clear, meaningful ways to sort. Common contexts include:
  • Search
  • Medications
  • Appointments
  • Secure messages
  • Claims
  • History
• When there’s 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 Table component.

Behavior

Web

• Clicking or tapping the component opens the 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 component 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 Sort by label is in line with the dropdown and the width is fixed. Choose the Medium (md), Large (lg), or Extra Large (xl) size, whichever prevents truncating the longest sort option.
  • On mobile resolutions, the Sort by label is stacked on top of the dropdown and the component is full-width and responsive.

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

• Note that the VA mobile app doesn’t 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.
  • 
• Keep sort option naming consistent across mobile and desktop experiences.

Code usage

• Using an API to sort and paginate data is acceptable. 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.

• Name sort options clearly and consistently using 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 how the results are ordered. 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
  • 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)

• Avoid offering a sort method as an option on its own. For example, if a Vaccine history card only shows a date value, label the sort option as Date received (newest to oldest) rather than Newest to oldest.

• Keep sort option labels consistent across mobile and desktop. If mobile uses Date filled (newest to oldest), desktop should use the same wording.

Additional guidance

• Only include sort options that are relevant to a user goal.

• Allow users to sort in both directions. This isn’t necessary when the reverse order isn’t meaningful or useful. For example, it may not make sense to sort VA locations from furthest to closest.

• Sort doesn’t 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’s 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

• Inform users when results have updated after a sort option is selected. This is especially important for screen reader users who may not see the visual change.
• Ensure sorted results update in a meaningful and predictable order so all users perceive the same sequence of information (WCAG 1.3.2 Meaningful Sequence).
• Update results in place during sorting and don’t trigger page navigation or a full context change.
• Keep focus stable on the sort control during sorting so users can continue interacting without losing their place.
• Inform users that an update is in progress if sorting takes time 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.