Components

USWDS components are designed to set a new bar for simplicity and consistency across government services.

Getting started. For getting up and running with USWDS, head over to our Getting started page for more information.

Importing only the components your project needs

Not every USWDS project needs to use the entire design system. We support incremental adoption, in part by allowing any USWDS project to import only the components they need.

To do this, we’re expanding the idea of packages that already existed in USWDS 2.0. The USWDS 2.0 version of packages allowed users to include only parts of the USWDS codebase by using @importing specific files within stylesheets/packages. (See the theme stylesheet for an example of this.) The initial version of packages allowed importing only the fonts, the components, the utilities, or the layout grid. Packages (starting in USWDS 2.1) are much more granular and modular.

Now we consider a package to be a discrete unit of functionality — typically a component (like search). These packages are kept in stylesheets/packages and they point to each functional unit’s dependencies and source code. For example, the usa-search package looks like this:

// dependencies
@import '../base/accessibility';
@import '../elements/form-controls/global';
@import '../elements/form-controls/text-input';
@import 'usa-button';

// src
@import '../components/search';

If developers want to use the usa-search component, @importing packages/usa-search into their stylesheet will import all the styles necessary to make the component work.

Required and global package dependencies

USWDS packages attempt to improve the performance of all this importing by requiring users @import certain non–code emitting internal Sass required of every component once. (This is Sass like mixins, settings, and functions.) These are collected in the required package.

packages/required:

@import '../settings/settings-general';
@import '../settings/settings-typography';
@import '../settings/settings-color';
@import '../settings/settings-spacing';
@import '../settings/settings-utilities';
@import '../settings/settings-components';
@import '../core/functions';
@import '../core/system-tokens';
@import '../core/variables';
@import '../core/properties';
@import '../core/mixins/all';
@import '../core/placeholders/all';

There’s also a set of basic code-emitting global styles necessary for the best performance of components. These are collected in the global package.

packages/global:

@import '../lib/normalize';
@import '../global/font-face';
@import '../global/focus';
@import '../global/sizing';
@import '../global/typography';

Using packages

Use packages as you would any USWDS import: import required, global and any individual functional packages after importing your project’s theme settings, and before importing your project’s custom styles. For example (assuming './node_modules/uswds/dist/scss' in your sass.includePaths) the following file would import only the USWDS code necessary to render the banner and footer components:

// styles.scss
// import your project theme settings
@import 'uswds-theme-general';
@import 'uswds-theme-typography';
@import 'uswds-theme-spacing';
@import 'uswds-theme-color';
@import 'uswds-theme-utilities';

// then any packages
@import 'packages/required';
@import 'packages/global';
@import 'packages/usa-banner';
@import 'packages/usa-footer';

// then any custom Sass
@import 'my-custom-sass';

The current method of using @import uswds to import everything has not changed.

Reducing footprint with packages

Using packages to subset your CSS can result in a dramatic reduction of your overall USWDS footprint. Using packages can also reduce the build time of your project.