What’s new in USWDS 2.10

New components

We have four new components in this release. Learn more about each of them on our website:

• Collection: A collection displays a compact list of multiple related items like articles or events. The list links each item to its original source.
• Process list: A process list displays the steps or stages of important instructions or processes.
• Site alert: A site alert communicates urgent sitewide information.
• Summary box: A summary box highlights key information from a longer page or displays next steps.

Updated components

We have four updated components in this release. Learn more about each of them on our website:

• Checkbox (tile display): We added a "tile" display to provide a larger, more obvious touch target for checkboxes.
• Icons: We improved our default icon support and now provide a broader selection of consistent icons in our package.
• Radio button (tile display): We added a "tile" display to provide a larger, more obvious touch target for radio buttons, as well.
• Table (mobile and data display): We improved the mobile performance of our tables and included more formatting options for data tables.

New templates

We have three new templates in this release. Learn more about each of them on our website:

• Create account: Create a new account
• Sign in: Sign in to a service
• Sign in (multiple sign-in options): Choose from multiple sign-in providers

No more banner flash: The USWDS initializer script

USWDS 2.10.0 adds a small (under 1 KB minified) initialization script (uswds-init.min.js) to the package. When included in the <head> — either by reference or inline — this script prevents the banner from flashing its content on page load and shifting content (#3092).

Note: This only prevents flashing when you use CSS generated from USWDS 2.10.0 or later.

What it does

Simply:

• It adds a .usa-js-loading class to the <html> element as the USWDS JS library is loading.

In more detail:

• If JavaScript is present, it adds a .usa-js-loading class to the <html> element before the body renders.
• If the USWDS JS library loads, it removes the .usa-js-loading class.
• If the USWDS JS library does not load in a timeout period, it removes the .usa-js-loading class.

Since USWDS components are meant to make their content available even if our JS does not load, their visibility of any toggle-able content defaults to visible and the JS is responsible for hiding it. This resulted in a flash of "hidden" content between when the page renders and the JS loads.

This initialization script allows us to visually hide "hidden" content at page render by hooking those styles to the .usa-js-loading class. When the USWDS JS loads, the JavaScript is responsible for hiding/showing interactive content as usual and the class hook is removed. If the USWDS JS does not load, uswds-init removes the .usa-ls-loading class and the content will revert to visible. If there is no JS present at all, uswds-init will not load and the content will be visible at page render.

Using the initializer

1. Copy uswds-init-min.js out of the USWDS package an into your project directory.
2. Reference the script in the document <head> or include the entire script inline.

Include by reference

<!DOCTYPE html>
<html>
  <head>
    ...
    <script src="assets/uswds/js/uswds-init.min.js"></script>
    <link rel="stylesheet" href="assets/uswds/css/uswds.min.css" />
  </head>
  <body>
    ...
    <script src="assets/uswds/js/uswds.min.js"></script>
  </body>
</html>

Include inline

<!DOCTYPE html>
<html>
  <head>
    ...
    <script>
      const docElem=window.document.documentElement,loadingClass="usa-js-loading";function addLoadingClass(){docElem.className+=` ${loadingClass}`}function revertClass(){docElem.className=docElem.className.replace(loadingClass,"")}if("querySelector"in window.document&&"addEventListener"in window){addLoadingClass();const e=setTimeout(revertClass,8e3);let s=100;const n=()=>{setTimeout(()=>{s+=1,"undefined"!=typeof uswdsPresent?(clearTimeout(e),setTimeout(revertClass,100)):s>0&&n()},100)};n()}
    </script>
    <link rel="stylesheet" href="assets/uswds/css/uswds.min.css" />
  </head>
  <body>
    ...
    <script src="assets/uswds/js/uswds.min.js"></script>
  </body>
</html>

Other improvements and bug fixes

Improved non-autoprefixed state of colored icons. When you see a USWDS icon that appears as a rectangle instead of its proper shape, this is because some USWDS colored icons require Autoprefixer to display properly. Now the non-Autoprefixer icon will appear as a black icon instead of as a rectangle. All projects should still use Autoprefixer when compiling their stylesheets. Thanks @aduth! (#3860)

Improved the accessibility of decorative images in the Banner. We modified the Banner to properly mark up SVG files used as decorative images. Now all decorative images are hidden from screen readers, and all SVGs are more resilient to browser bugs. See the Banner page for the complete, correct markup, and see the pull request for more context on the changes. (#3892)

⚠️ This requires a manual change on any site that uses the Banner.

• Use alt="" for any decorative <img> element
• Use role="img" for <img> elements with an SVG source
• Use aria-hidden="true" for decorative <img> elements with an SVG source
• Use role="img" and focusable="false" for <svg> elements meant to be images (ie don't contain text/data)
• Use aria-hidden="true" for decorative <svg> elements
• Use aria-label="[accessible name]" or aria-labelledby="[id list]" for <svg> elements that convey information and need an accessible description

Created a Spanish version of the Search component. We recommend using "Buscar" in Spanish-language version of Search. See the Search guidance page for more information. Thanks @lggsa! (#3861)

Updated the Spanish USAGov link in the identifier. The Spanish-language USAGov link in the identifier should read Visite USAGov en Español (#3863)

⚠️ This requires a manual change on any site that uses the Spanish-language identifier.

Visite USA.gov en Español → Visite USAGov en Español

Support custom bold font weight. Now $theme-font-weight-bold will change the theme bold font weight as expected. Thanks @sawyerh! (#3811)

Allow proper drag/drop on File input component. Now drag and drop will accept or reject files as expected when using a File input set to accept multiple extensions. Thanks @ConnorDY! (#3851)

Enable proper hover styles on visited links. Now visited links have a visible hover state. Thanks @astiefvater! (#3868)

Enable and disable File Input programmatically. Now developers can set the status of the File Input component dynamically. Thanks @ConnorDY! (#3760)

Better support for buttons with multiple variants. We fixed a display bug with visited inverse unstyled buttons. Button styling is more reliable with different combinations of variants. Thanks @andycochran! (#3846)

Support buttons in side navigation. Now any anchor link button in a Side Navigation component hill have expected display. Thanks @ajware-uscis! (#3839)

Allow custom hex colors as File Input disabled color. We fixed a bug that prevented a custom hex value for disabled-light from working in the File Input component. Thanks @aduth! #3762

Improved font display in the Identifier. We're now using normal weight text in the Identifier domain text instead of light text for more consistent appearance. (#3740)

Improved breadcrumb padding. Fixes a bug that could make some values of $theme-focus-width incompatible with the Breadcrumb. (#3737)

Dependencies and security

0 vulnerabilities in regular dependencies (dependencies for USWDS projects installed with npm install uswds)

5 low, 2 high vulnerabilities in devDependencies (development dependencies)

Release ZIP SHA-256 hash: 1c3c31de6fdb62bd327b54e46c1513a252ffc4a54b9152db1e2fcafb7dbc4c4e