You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository is currently being migrated. It's locked while the migration is in progress.
intro-text: "The Sort component allows users to reorder search results and lists of information to make information easier to analyze."
8
+
web-component: va-sort
7
9
web: true
8
10
mobile-app: false
9
-
intro-text: "The Sort component allows users to reorder search results and lists of information to make information easier to analyze."
10
-
# github-title: va-component-name - Only use this if the component is not actually a web component and thus just needs a label that matches that format.
11
-
# research-title: Use this to match the label in the research repo. Only use if web-component does not match the label.
{% include storybook-preview.html story="components-va-sort--default" link_text="va-sort default" %}
26
+
27
+
### Custom Default Value
28
+
29
+
{% include storybook-preview.html story="components-va-sort--custom-default-value" link_text="va-sort--custom-default-value" %}
30
+
31
+
### Widths
32
+
33
+
{% include storybook-preview.html story="components-va-sort--widths" link_text="va-sort--widths" %}
34
+
35
+
### Mockups
36
+
37
+
#### Medications (Mobile)
30
38
31
-
#### Mobile
32
39
{% include component-example.html alt="Mobile example of medications on the My HealtheVet Medications page placed below the Filter and above the search results." file="/images/components/sort/medications_sort_mobile.png" caption="Mobile example of My HealtheVet medications sorted by last fill date (newest to oldest) alongside the Search Filter component." width="25%" %}
33
40
34
-
#### Desktop
41
+
#### Medications (Desktop)
35
42
{% include component-example.html alt="Desktop example of medications on the My HealtheVet Medications page placed below the Filter and above the search results" file="/images/components/sort/medications_sort.png" caption="Desktop example of My HealtheVet medications sorted by last fill date (newest to oldest) alongside the Search Filter component." width="50%" %}
36
43
37
-
### Questions
44
+
####Questions
38
45
{% include component-example.html alt="Desktop example of Sort placed below the Search Input component, separated by a divider with the Search Filter in a column to the left." file="/images/components/sort/askva_sort_search_input_filter.png" caption="Desktop example of AskVA questions sorted by last updated (newest to oldest) alongside the Search Input and Search Filter components." width="50%" %}
39
46
40
-
### Find a Form
47
+
####Find a Form
41
48
{% include component-example.html alt="Screenshot of the VA Find a Form search results page showing a Sort by dropdown set to the default option above a list of form results." file="/images/components/sort/find_a_form_sort.png" caption="Desktop example of VA forms sorted by relevance on VA Find a Form." width="50%" %}
42
49
43
-
### Secure Messaging
50
+
####Secure Messaging
44
51
{% include component-example.html alt="Example of messages sorted by send date (newest to oldest) in the My HealtheVet Inbox" file="/images/components/sort/inbox_sort.png" caption="Desktop example of messages sorted by last updated (newest to oldest) in the My HealtheVet Inbox." width="50%" %}
45
52
46
53
47
54
## Usage
48
55
49
56
### When to use Sort
50
57
51
-
***When there are clear, meaningful ways to sort.**Sort options should help users achieve their goals. Common contexts include:
52
-
* Search results
58
+
***When there are clear, meaningful ways to sort.** Common contexts include:
59
+
* Search
53
60
* Medications
54
61
* Appointments
55
62
* Secure messages
@@ -67,11 +74,12 @@ anchors:
67
74
* For example, don't use Sort to filter by date ranges. <imgsrc="{{ site.baseurl }}/images/components/sort/sort_nonexample.png"alt="Nonexample where Sort is being used to filter by a date range"style="width:50%;"/>
68
75
***When sorting within a table**, use the sort columns baked into the `va-table` component.
69
76
70
-
## Behavior
71
77
72
-
### Web
78
+
### Behavior
73
79
74
-
***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]({{ site.baseurl }}/components/form/select) as the foundation and shares similar behavior.
80
+
#### Web
81
+
82
+
***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]({{ site.baseurl }}/components/form/select) as the foundation and shares similar behavior.
75
83
76
84
***Results automatically update when you select a sort option.** This is known as implicit submission.
77
85
***Why implicit submission?**
@@ -84,28 +92,26 @@ anchors:
84
92
***Sort selections persist across interactions.** The sort criteria should remain when users navigate through paginated results or refresh the page.
85
93
86
94
***Sizing and alignment differ on mobile and desktop.**
87
-
* On desktop resolutions, the width is fixed and the *Sort by* label is in line with the dropdown.
88
-
* Choose Medium (md), Large (lg), or Extra Large (xl) size, whichever prevents truncating the longest sort option.
89
-
* On mobile resolutions, the component is full-width and responsive. The *Sort by* label is stacked on top of the dropdown.
90
-
95
+
* 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.
96
+
* On mobile resolutions, the *Sort by* label is stacked on top of the dropdown and the component is full-width and responsive.
91
97
92
98
93
-
### Placement
99
+
####Placement
94
100
95
101
***Place Sort above and aligned with the content that it affects.** It serves as a visual indicator of the current order.
96
-
***If used with the Search Filter, place Sort after the Search Filter's [results description](https://design.va.gov/templates/search-results#results-description:~:text=the%20sorting%20options.-,Results%20description,-Text%20describing%20how).** 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.
102
+
***Place Sort after the Search Filter's [results description]({{ site.baseurl }}/templates/search-results#results-description) when used with filtering.** 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.
97
103
98
104
### Mobile app
99
105
100
-
***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.
106
+
***Note that 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.
101
107
* <imgsrc="{{ site.baseurl }}/images/components/sort/va_mobile_filter_sort.png"alt="A Filter and Sort button that opens a modal that allows a user to explicitly submit sort and filter options."style="width:100%;"/>
102
108
103
-
***The naming of sort options must still remain consistent across mobile and desktop experiences.**
109
+
***Keep sort option naming consistent across mobile and desktop experiences.**
104
110
105
111
112
+
{% include component-docs.html component_name=page.web-component %}
106
113
107
-
## Code usage
108
-
***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.
114
+
***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.
109
115
* Store date and time as an [ISO-formatted string](https://en.wikipedia.org/wiki/ISO_8601#:~:text=Date%20and%20time%0Ain,00%20UTC%E2%88%9212%3A00) (date and time in UTC or date and time with offset).
110
116
* 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:
111
117
* ***1****0/1/2024*
@@ -117,16 +123,17 @@ anchors:
117
123
* *9/5/****2023***
118
124
119
125
126
+
120
127
## Content considerations
121
128
122
129
### Content expectations
123
130
***Provide a default sort option** that reflects what users expect in the given context. In search experiences, *Relevance* is often the default.
124
-
* Don't present a placeholder option (such as *- Select -*) as a selectable sort choice.
125
131
126
-
***Name sort options clearly and consistently** so users understand both *what* is being sorted and *how* it's ordered.
127
-
* Use this convention: `[Sort attribute] (sort method)`
128
-
* `[Sort attribute]` describes what the results are sorted by (for example, medication name, entry date, or distance).
129
-
* `(Sort method)` describes the ordering. Use familiar, plain language terms such as:
132
+
***Name sort options clearly and consistently** using this convention:
133
+
*`Sort attribute (sort method)`
134
+
* `Sort attribute` describes what the results are sorted by.
135
+
* Examples: Medication name, entry date, distance
136
+
* `(Sort method)` describes how the results are ordered. Use familiar, plain language terms such as:
130
137
* **Alphabetical**
131
138
* A to Z
132
139
* **Chronological**
@@ -137,36 +144,36 @@ anchors:
137
144
* Smallest to largest
138
145
* Lowest to highest
139
146
* Shortest to longest
140
-
***Note:** Avoid offering a sort method on its own without clearly identifying the attribute being sorted.
141
-
* 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*.
142
147
* Examples of clear and consistent sort option labels include:
143
148
**Medication name (A to Z)*
144
149
**Date entered (newest to oldest)*
145
150
**Refills remaining (least to most)*
146
151
**Distance (closest to furthest)*
147
152
148
-
***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)*.
153
+
***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*.
154
+
155
+
***Keep sort option labels consistent across mobile and desktop.** If mobile uses *Date filled (newest to oldest)*, desktop should use the same wording.
149
156
150
157
151
158
### Additional guidance
152
-
***Consider allowing users to sort in both directions**—for example, A to Z and Z to A.
153
-
* 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.
154
-
155
-
***Only include sort options that provide clear value.** The ability to sort data doesn't automatically mean it will help users.
156
159
157
-
***Sort does not need to be reflected in the [results description](https://design.va.gov/templates/search-results#results-description:~:text=the%20sorting%20options.-,Results%20description,-Text%20describing%20how) 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.
160
+
***Only include sort options that are relevant to a user goal.**
161
+
162
+
***Allow users to sort in both directions.** This is not necessary when the reverse order is not meaningful or useful. For example, it may not make sense to sort VA locations from furthest to closest.
163
+
164
+
***Sort does not need to be reflected in the [results description]({{ site.baseurl }}/templates/search-results#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.
158
165
159
166
160
167
161
168
## Accessibility considerations
162
169
These considerations describe how sorting changes are communicated and experienced by users of assistive technologies.
163
170
164
171
### User experience expectations
165
-
*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.
166
-
*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](https://www.w3.org/WAI/WCAG21/Understanding/meaningful-sequence.html)).
167
-
*Sorting updates the results in place and does not trigger page navigation or a full context change.
168
-
*Focus remains stable on the sort control during sorting so users can continue interacting without losing their place.
169
-
*If sorting takes time, inform users that an update is in progress by following the [loading indicator guidance]({{ site.baseurl }}/components/loading-indicator).
172
+
*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.
173
+
*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](https://www.w3.org/WAI/WCAG21/Understanding/meaningful-sequence.html)).
174
+
*Update results in place during sorting and do not trigger page navigation or a full context change.
175
+
*Keep focus stable on the sort control during sorting so users can continue interacting without losing their place.
176
+
*Inform users that an update is in progress if sorting takes time by following the [Loading Indicator guidance]({{ site.baseurl }}/components/loading-indicator).
170
177
171
178
### Implementation notes
172
179
* 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.
0 commit comments