va-sort: add new component by jamigibbs · Pull Request #1963 · department-of-veterans-affairs/component-library

jamigibbs · 2026-01-29T20:36:08Z

Chromatic

https://4637-sort-component--65a6e2ed2314f7b8f98609d8.chromatic.com

Description

This PR will add the new va-sort web component.

Screenshots

https://design.va.gov/foundation/breakpoints

Tablet (640px) and above

Below Tablet

Below tablet, width is always 100%

Testing and review

Approvals

See the QA Checklists section below for suggested approvals. Use your best judgment if additional reviews are needed. When in doubt, request a review.

Approval groups

Add approval groups to the PR as needed:

Engineering: platform-design-system-fe
Accessibility: platform-design-system-a11y
Design: platform-design-system-designer

QA checklists

Use the QA checklists below as guides, not rules. Not all checklists will apply to every PR but there could be some overlap.

In all scenarios, changes should be fully tested by the author and verified by the reviewer(s); functionality, responsiveness, etc.

✨ New Component Added

🌱 New Component Variation Added

The PR has the minor label
The variation matches its Figma design.
Any new properties, custom events, or utility functions have e2e and/or unit tests
A new story has been added to the component's existing Storybook page
Any Chromatic UI snapshot changes have been accepted by a design reviewer
Tested in vets-website using Verdaccio
Engineering has approved the PR
Design has approved the PR

🐞 Component Fix

The PR has the patch label
Any new properties, custom events, or utility functions have e2e and/or unit tests
Any markup changes are evaluated for impact on vets-website.
- Will any vets-website tests fail from the change?
Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
Engineering has approved the PR

♿️ Component Fix - Accessibility

The PR has the patch label
Any new properties, custom events, or utility functions have e2e and/or unit tests
Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
Engineering has approved the PR
Accessibility has approved the PR

🚨 Component Fix - Breaking API Change

The PR has the major label
vets-website and content-build have been evaluated to determine the impact of the breaking change
Any new properties, custom events, or utility functions have e2e and/or unit tests
Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
Tested in vets-website using Verdaccio
Engineering has approved the PR

🔧 Component Update - Non-Breaking API Change

The PR has the minor label
Any new properties, custom events, or utility functions have e2e and/or unit tests
Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
Engineering has approved the PR

📖 Storybook Update

The PR has the ignore-for-release label
Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
Engineering has approved the PR

🎨 CSS-Library Update

The PR has the css-library label
vets-website and content-build have been checked to determine the impact of any breaking changes
Engineering has approved the PR

jamigibbs · 2026-02-02T16:10:40Z

+   * Displays the select at a specific width. Accepts md or medium (20ex), lg (30ex), xl (40ex).
+   */
+  // eslint-disable-next-line i18next/no-literal-string
+  @Prop() width: string = 'lg';


note: The enforcement of these specific options (md, lg, & xl) is done by using a dedicated class in the uswds-input-width Sass file.

jamigibbs · 2026-02-02T16:12:54Z

+  /**
+   * Whether or not to fire the analytics events
+   */
+  @Prop() enableAnalytics?: boolean = false;


question The va-select component makes analytics opt-in using this property enableAnalytics. This is standard for all form component to avoid unintentionally leaking PII/PHI.

Is the va-sort component considered a forms component though? If not, then we could make analytics opt-out by changing this to disableAnalytics.

jamigibbs · 2026-02-02T16:18:08Z

@@ -1,25 +1,37 @@
+$system-input-widths: (


note: I wrote this as a comment in the file itself but adding it here too for visibility; this Sass variable declaration $system-input-widths is intended to be temporary until we update the USWDS package version.

When USWDS is updated to v3.11.0+, we should instead use:

@use 'uswds-core' as *;

...and the $system-input-widths mapping will be available in the uswds-core package directly. As of this writing, the web-components package is using v3.9.0

related issue:

Dependencies: Use current version of USWDS vets-design-system-documentation#5092

jamigibbs · 2026-02-02T16:20:50Z

+          selectLabel: this.value,
+        },
+      };
+      this.componentLibraryAnalytics.emit(detail);


note: I will be reaching out to the analytics team to let them know we are adding a new component with analytics. A PR to vets-website will follow.

Draft vets-website PR:

Add new va-sort component for connecting Google Analytics vets-website#41966

…f-veterans-affairs/component-library into 4637-sort-component

powellkerry · 2026-02-04T16:03:35Z

@@ -0,0 +1,119 @@
+import { Component, Host, h, Prop, Event, EventEmitter } from '@stencil/core';
+


The jsDoc section is missing with the @componentName, @maturityCategory, and @maturityLevel

derekwang99 · 2026-02-04T19:50:46Z

Hi @jamigibbs thanks for taking on this component! Can the spacing between Sort by and Relevance in the in-line/desktop view be modified to be 8px apart? I think it's currently 16?

derekwang99 · 2026-02-05T18:48:00Z

Hi @jamigibbs! Some additional suggestions to implement as discussed from Standup today:

On mobile devices, Sort should be full width (so for Small and XSmall screens full-width behavior should override the default Sort size)
The sort options should be changed to reflect guidance
- Sort by
  - Relevance
  - Medication name (A to Z)
  - Medication name (Z to A)
  - Fill date (newest to oldest)
  - Fill date (oldest to newest)

Also wanted to add 2 other suggestions:

From Dan: change the name of Custom Value story to Custom Default Value
From me: change the name of Custom Width story to Widths (to match Select) + can the spacing between h4 and component and spacing between each width variation in Small/XSmall match the spacing in Medium+ ?

jamigibbs · 2026-02-06T16:05:16Z

@derekwang99 Thanks for that feedback! I've made updates to address them and you're welcome to review again. 🙏🏻

derekwang99

LGTM, thanks Jami!

jamigibbs · 2026-02-06T18:35:22Z

+      // flex-basis instead of max-width in order to adjust the width
+      @media (min-width: tokens.$tablet) {
+        max-width: none;
+        flex-basis: map-get($system-input-widths, $size);


note: The sort component has a dedicated class for applying width for two reasons:

It should only support specific widths

The container has been changed to flex to allow for the label to be positioned horizontally to the select field so it needs to use flex-basis to set the initial size of the container. max-width does not work with flex.

jamigibbs · 2026-02-06T18:37:12Z

+:host .va-select__sort-container {
+  @each $size in ('md', 'medium', 'lg', 'xl') {
+    &--#{$size} {
+      max-width: 100%;


note: Mobile web viewports should always display the select as full width so the width class will default to a max-width: 100% here (flex-basis is only needed in desktop). When it gets to the the $tablet breakpoint and larger though, the pre-defined width values will apply.

jeana-adhoc

We should enable axeCheck for the component

jeana-adhoc · 2026-02-06T22:12:58Z

+const defaultArgs = {
+  'name': 'options',
+  'value': '',
+  'message-aria-describedby': 'Optional description text for screen readers',


Do we need to define this for the storybook stories? I can't think of what this could be. I know it's in the architect doc https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/products/platform/design-system/components/va-sort/properties-architecture.md#properties and we have it in the va-select now. If we don't have to define for for the stories, I'd like not to. If we do, let me know and I'll try to come up with something more realistic.

@jeana-adhoc Nah, we don't need it. I'll remove it. If you decide to put something more realistic there though, just let me know.

jeana-adhoc

LGTM!

va-sort component checklist complete (🔒 Google Sheet)

initial

a7922bd

jamigibbs added the minor For a minor Semantic Version change label Jan 29, 2026

jamigibbs added 2 commits February 2, 2026 09:24

add analytics event

1d899f1

minor style and storybook updates

2f3fddb

jamigibbs commented Feb 2, 2026

View reviewed changes

jamigibbs added 2 commits February 2, 2026 10:19

cleanup

d3255bb

Merge branch 'main' into 4637-sort-component

f6cd8db

jamigibbs commented Feb 2, 2026

View reviewed changes

jamigibbs requested review from a team February 2, 2026 16:33

jamigibbs marked this pull request as ready for review February 2, 2026 16:34

jamigibbs requested a review from a team as a code owner February 2, 2026 16:34

jamigibbs added 6 commits February 2, 2026 10:48

pinning version to try and fix build error

33c3982

update chromatic action to last non-breaking release

8f5fbf8

Merge branch 'main' into 4637-sort-component

0236edf

add additional storybook stories

81538ac

Merge branch '4637-sort-component' of https://github.com/department-o…

7017846

…f-veterans-affairs/component-library into 4637-sort-component

Merge branch 'main' into 4637-sort-component

6ec1150

jamigibbs mentioned this pull request Feb 3, 2026

va-sort: update event name in guidelines department-of-veterans-affairs/vets-design-system-documentation#5621

Merged

Merge branch 'main' into 4637-sort-component

21bd092

powellkerry reviewed Feb 4, 2026

View reviewed changes

jamigibbs added 2 commits February 4, 2026 10:54

add jsDoc frontmatter

17a894b

add breakpoint style adjustment for label position

9c23246

update desktop column gap

3b3a34e

derekwang99 self-requested a review February 4, 2026 23:14

jamigibbs added 2 commits February 6, 2026 09:00

remove redundant declarations

fbba87c

update story options

6edd4be

jamigibbs added 3 commits February 6, 2026 09:10

make select full width below tablet breakpoint

c860255

update story names

e35987e

adjust width to always be 100% below tablet breakpoint

9a62359

Merge branch 'main' into 4637-sort-component

229e37d

derekwang99 approved these changes Feb 6, 2026

View reviewed changes

jamigibbs requested a review from a team February 6, 2026 18:33

jamigibbs commented Feb 6, 2026

View reviewed changes

add axeCheck test

9e8eeae

jeana-adhoc reviewed Feb 6, 2026

View reviewed changes

powellkerry approved these changes Feb 6, 2026

View reviewed changes

jeana-adhoc suggested changes Feb 6, 2026

View reviewed changes

remove aria prop from storybook stories

8926d19

jamigibbs requested a review from jeana-adhoc February 10, 2026 15:20

jeana-adhoc approved these changes Feb 10, 2026

View reviewed changes

Merge branch 'main' into 4637-sort-component

3bfc999

jamigibbs merged commit 46c36ff into main Feb 10, 2026
7 of 8 checks passed

jamigibbs deleted the 4637-sort-component branch February 10, 2026 21:51

jeana-adhoc mentioned this pull request Feb 10, 2026

Sort-search component - Accessibility review department-of-veterans-affairs/vets-design-system-documentation#5097

Closed

9 tasks

This was referenced Feb 16, 2026

Update package versions for v55.0.0 release #1994

Closed

Update package versions for v54.7.0 release #1996

Merged

		@@ -0,0 +1,119 @@
		import { Component, Host, h, Prop, Event, EventEmitter } from '@stencil/core';

Conversation

jamigibbs commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Chromatic

Description

Related tickets and links

Screenshots

Tablet (640px) and above

Below Tablet

Below tablet, width is always 100%

Testing and review

Approvals

QA checklists

Uh oh!

jamigibbs Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jamigibbs Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jamigibbs Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jamigibbs Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

jamigibbs Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

powellkerry Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

jamigibbs Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

derekwang99 commented Feb 4, 2026

Uh oh!

derekwang99 commented Feb 5, 2026

Uh oh!

jamigibbs commented Feb 6, 2026

Uh oh!

derekwang99 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jamigibbs Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

jamigibbs Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeana-adhoc left a comment

Choose a reason for hiding this comment

Uh oh!

jeana-adhoc Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

jamigibbs Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

jeana-adhoc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jamigibbs commented Jan 29, 2026 •

edited

Loading

jamigibbs Feb 2, 2026 •

edited

Loading

jamigibbs Feb 2, 2026 •

edited

Loading

jamigibbs Feb 2, 2026 •

edited

Loading

derekwang99 left a comment •

edited

Loading

jamigibbs Feb 6, 2026 •

edited

Loading