Components

Packages

USWDS component packages allow you to import only the components your project needs.

Introducing packages

Few USWDS projects need to use the entire design system. Include only the code your project needs with USWDS packages.

Packages are discrete units of functionality. Most USWDS packages are components (like usa-search, usa-banner, or usa-accordion), but packages can also include items like fonts (uswds-fonts), bundles of components (uswds-form-controls), or simply USWDS mixins, functions, and tokens (uswds-core).

Instead of including everything the design system offers by using the uswds package with code like the following:

@forward "uswds";

You can include only the code you need, with something like:

@forward "usa-accordion";
@forward "usa-button";
@forward "usa-banner";
@forward "usa-identifier";

Using packages helps reduce unused code, reduces the size of the final compiled CSS, and typically results in faster compile times. The uswds package included by default in most projects is 73 KB gzipped. Using packages typically cuts that number by half.

With packages and Sass module syntax in USWDS 3.0, you can be confident that packages that share code dependencies will only include those dependencies once in a project.

The uswds-core package

The uswds-core package is a new package in USWDS 3.0. uswds-core is the engine of the design system, and includes all the functions, mixins, placeholders, tokens, and fonts necessary to write USWDS Sass.

Any custom Sass you write needs to @use "uswds-core" at the top of the file to load the USWDS design language. We suggest using @use "uswds-core" as * to add USWDS to the global namespace. For example:

/* custom-styles.scss */

@use "uswds-core" as *;

.custom-component {
  @include u-bg("primary-vivid");
}

...

Included packages

USWDS includes 74 packages — a package for each component or named class group (prefixed with usa-), and a handful of bundle packages that collect multiple components together (prefixed with uswds-).

Using any package in your code will install the code for the component, plus dependency code related to that component. The following table shows each USWDS package with its gzipped size, full size, source code size, and dependencies.

Package name Gzip size Full size Source size Dependencies
usa-accordion 1.85 KB 10 KB 3 KB usa-icon, uswds-fonts
usa-alert 2.405 KB 13 KB 7 KB usa-icon, uswds-fonts
usa-banner 5.92 KB 32 KB 7 KB usa-media-block, uswds-fonts
usa-breadcrumb 2.22 KB 12 KB 6 KB usa-icon, uswds-fonts
usa-button 2.96 KB 16 KB 9 KB uswds-fonts
usa-button-group 3.33 KB 18 KB 3 KB usa-button
usa-card 2.035 KB 11 KB 5 KB uswds-fonts
usa-character-count 0.185 KB 1 KB 0.2 KB uswds-core
usa-checkbox 1.85 KB 10 KB 3 KB usa-fieldset, usa-input-list, usa-legend, uswds-fonts
usa-checklist 1.295 KB 7 KB 0.7 KB usa-icon, uswds-fonts
usa-collection 1.665 KB 9 KB 3 KB uswds-fonts
usa-combo-box 1.85 KB 10 KB 3 KB usa-icon, usa-select
usa-content 0.037 KB 0.2 KB 0.2 KB uswds-core
usa-dark-background 0.074 KB 0.4 KB 0.4 KB uswds-core
usa-date-picker 3.145 KB 17 KB 10 KB usa-icon, usa-input, uswds-fonts
usa-date-range-picker 3.145 KB 17 KB 0 KB usa-date-picker
usa-display 1.295 KB 7 KB 0.8 KB uswds-fonts
usa-embed-container 0.0555 KB 0.3 KB 0.3 KB uswds-core
usa-error-message 1.11 KB 6 KB 0.1 KB uswds-fonts
usa-fieldset 1.295 KB 7 KB 0.2 KB usa-input, uswds-fonts
usa-file-input 1.85 KB 10 KB 4 KB uswds-fonts
usa-footer 7.955 KB 43 KB 7 KB usa-button, usa-form, usa-icon, usa-input, usa-label, usa-layout-grid, usa-list, uswds-fonts
usa-form 1.48 KB 8 KB 1 KB uswds-fonts
usa-form-group 1.11 KB 6 KB 1 KB uswds-fonts
usa-graphic-list 4.625 KB 25 KB 0.9 KB usa-layout-grid, uswds-fonts
usa-header 6.845 KB 37 KB 6 KB usa-accordion, usa-button, usa-nav, usa-search, usa-skipnav, uswds-fonts, uswds-helpers
usa-hero 4.625 KB 25 KB 0.7 KB usa-layout-grid, uswds-fonts
usa-hint 1.295 KB 7 KB 0.2 KB usa-input, uswds-fonts
usa-icon 0.074 KB 0.4 KB 0.4 KB uswds-core
usa-icon-list 4.07 KB 22 KB 16 KB usa-input, uswds-fonts
usa-identifier 1.665 KB 9 KB 3 KB uswds-core, uswds-fonts
usa-input 1.295 KB 7 KB 0.5 KB uswds-fonts
usa-input-prefix-suffix 1.48 KB 8 KB 1 KB usa-icon, usa-input
usa-intro 1.11 KB 6 KB 0.2 KB uswds-fonts
usa-label 1.11 KB 6 KB 0.3 KB uswds-fonts
usa-layout-docs 0.037 KB 0.2 KB 0.2 KB uswds-core
usa-layout-grid 3.33 KB 18 KB 18 KB uswds-core
usa-legend 1.11 KB 6 KB 0.3 KB uswds-fonts
usa-link 1.48 KB 8 KB 1 KB usa-icon, uswds-fonts
usa-list 0.0925 KB 0.5 KB 0.5 KB
usa-media-block 0.0185 KB 0.1 KB 0.1 KB
usa-memorable-date 1.295 KB 7 KB 0.6 KB usa-form-group, usa-input, uswds-fonts
usa-modal 3.33 KB 18 KB 3 KB usa-button, uswds-fonts
usa-nav 5.55 KB 30 KB 9 KB usa-accordion, usa-icon, usa-search, uswds-fonts
usa-pagination 1.48 KB 8 KB 2 KB uswds-fonts
usa-paragraph 0.037 KB 0.2 KB 0.2 KB uswds-core
usa-process-list 1.48 KB 8 KB 2 KB uswds-fonts
usa-prose 4.44 KB 24 KB 18 KB uswds-fonts
usa-radio 1.48 KB 8 KB 1 KB usa-fieldset, usa-input-list, usa-legend, uswds-fonts
usa-range 1.48 KB 8 KB 2 KB usa-label, uswds-fonts
usa-search 3.33 KB 18 KB 1 KB usa-button, usa-icon, usa-input, uswds-fonts, uswds-helpers
usa-section 0.111 KB 0.6 KB 0.6 KB uswds-core
usa-select 1.48 KB 8 KB 1 KB usa-icon, usa-input, uswds-fonts
usa-sidenav 1.48 KB 8 KB 2 KB uswds-fonts
usa-site-alert 3.145 KB 17 KB 4 KB usa-alert
usa-site-title 0.0 KB 0 KB 0 KB
usa-skipnav 1.295 KB 7 KB 0.6 KB uswds-fonts
usa-step-indicator 2.22 KB 12 KB 6 KB uswds-fonts, uswds-helpers
usa-summary-box 1.295 KB 7 KB 0.9 KB usa-list, uswds-fonts
usa-table 3.885 KB 21 KB 15 KB uswds-fonts
usa-tag 1.295 KB 7 KB 1 KB uswds-fonts
usa-textarea 1.295 KB 7 KB 0.5 KB uswds-fonts
usa-time-picker 1.295 KB 7 KB 0.1 KB usa-hint, usa-input, usa-label, uswds-fonts
usa-tooltip 1.295 KB 7 KB 1 KB uswds-fonts
usa-validation 4.81 KB 26 KB 0 KB usa-alert, usa-button, usa-checklist, usa-fieldset, usa-form, usa-input, usa-label, usa-legend
uswds 72.89 KB 394 KB 0 KB
uswds-core 0.0 KB 0 KB 0 KB
uswds-elements 0.1295 KB 0.7 KB 0.7 KB
uswds-fonts 1.11 KB 6 KB 6 KB
uswds-form-controls 6.105 KB 33 KB 0 KB usa-character-count, usa-checkbox, usa-combo-box, usa-date-picker, usa-error-message, usa-fieldset, usa-file-input, usa-form, usa-form-group, usa-hint, usa-input, usa-input-prefix-suffix, usa-label, usa-legend, usa-memorable-date, usa-radio, usa-range, usa-select, usa-textarea, usa-time-picker
uswds-global 1.665 KB 9 KB 0 KB normalize, uswds-core, uswds-elements, uswds-fonts, uswds-helpers
uswds-helpers 0.037 KB 0.2 KB 0.2 KB sr-only, usa-focus
uswds-typography 4.995 KB 27 KB 0 KB usa-content, usa-dark-background, usa-display, usa-intro, usa-link, usa-list, usa-paragraph, usa-prose
uswds-utilities 36.63 KB 198 KB 198 KB

What’s in a package

As of USWDS 3.0, the USWDS codebase is organized around packages. Packages live in the top-level packages directory, and include not only Sass styles, but JavaScript, Twig templates, tests, assets, and sometimes content. Here’s what you’ll find in the usa-accordion package:

├── packages/
│   ...
│   ├── usa-accordion/
│   │   ├── src/
│   │   │   ├── content/
│   │   │   │   ├── index.js
│   │   │   │   ├── usa-accordion.json
│   │   │   │   ├── usa-accordion~bordered.json
│   │   │   │   ├── usa-accordion~multiselectable.json
│   │   │   ├── styles/
│   │   │   │   ├── _index.scss
│   │   │   │   └── accordion.scss
│   │   │   ├── test/
│   │   │   │   ├── accordion.spec.js
│   │   │   │   └── template.html
│   │   │   ├── index.js
│   │   │   ├── usa-accordion.stories.js
│   │   │   └── usa-accordion.twig
│   │   └── _index.scss

The /[package]/_index.scss file is the Sass entry point for the package styles. It forwards any package style dependencies in addition to the component source itself, which lives in [package]/src/styles/. The usa-search package entry point looks something like this:

/* ./packages/usa-search/_index.scss */

//dependencies
@forward "uswds-fonts";
@forward "uswds-helpers";
@forward "usa-button";
@forward "usa-icon";
@forward "usa-input";

// src
@forward "src/styles";

Importing package source only

Developers can save some compile time by bypassing the package Sass entry point, and forwarding straight to the package source. Only usa- prefixed packages have their own source files available to this technique.

Using this technique speeds up compiles, but requires that developers forward any package dependency manually. For instance, let’s imagine a project with the following packages in its Sass entry point:

@forward "usa-accordion";
@forward "usa-banner";
@forward "usa-button";
@forward "usa-identifier";
@forward "uswds-helpers";

Using only package source would result in the following:

@forward "usa-accordion/src/styles";
@forward "usa-banner/src/styles";
@forward "usa-button/src/styles";
@forward "usa-icon/src/styles";
@forward "usa-identifier/src/styles";
@forward "usa-layout-grid/src/styles";
@forward "usa-list/src/styles";
@forward "usa-media-block/src/styles";
@forward "uswds-core";
@forward "uswds-fonts";
@forward "uswds-helpers";

If you suffer from slow compiles, it may be worth experimenting with source forwarding.

Package Sass requirements: Load paths

Using USWDS 3.0 and packages requires compiling your Sass with load paths. Load paths tell your Sass compiler where to look for USWDS packages. Any compiler needs to include a load path to the @uswds/uswds/packages directory:

"./node_modules/@uswds/uswds/packages"

In a gulpfile, use includePaths in your sass() function.

  sass({
    includePaths: [
      "./node_modules/@uswds/uswds/packages",
    ],
  })

In webpack, include includePaths within the sassOptions of your Sass loader:

loader: "sass-loader",
options: {
  sassOptions: {
    includePaths: [
      "./node_modules/@uswds/uswds/packages",
    ],
  },
},

Using uswds-compile sets load paths automatically and can be a good way to build a reliable compile workflow into your project.

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date Description
2022-04-28

Updated instructions for using packages with USWDS 3.0. Added Sass module syntax, updated package list, and updated load paths. More information: uswds-site#1538