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 |
