Utilities Overview

Utilities are simple HTML classes typically scoped to a single CSS property, like border-style or background-color. Utilities can be used additively to style an object from scratch or to override a style defined in component CSS. Utilities allow designers and developers to build and test new designs and components without abstracting their work into traditional semantic names or altering production CSS.

They also make it possible to create element-specific overrides without writing high-specificity variants into component CSS.

Utility Naming

Most USWDS utilities are built to assign a single CSS property a single value. Our utilities are named .[base]-[value], where [base] is often the name of the CSS property the utility targets and the parts of the utility name are separated by a hyphen. For example, margin-top-2. Our utility classes are designed to make sense at a glance to anyone familiar with standard CSS properties.

For a complete list of the utilities and their bases, see each utility’s documentation page, or the Modules table, below.

The utility values are drawn from your project theme-settings tokens but can be extended to include additional values drawn from our palette of common units (like px, em, ch, and percentages) as well as the broader USWDS system palette of colors, grid spacing, and font scale. (Each utility’s Advanced settings section provides more information on customization.)

Utility Class Modifiers

Utility modules can be configured to output additional CSS classes for targeting specific breakpoints or the link-related pseudo-classes. Each utility module under Foundations documents which modifiers are enabled by default.

Responsive Modifiers

Add a responsive breakpoint prefix separated with a : to target a utility at a responsive breakpoint and higher, following a mobile-first methodology.

Example

.tablet:padding-y-2

Output

@media screen and (min-width: 640px) {
    .tablet\:padding-y-2 {
        padding-top: 1rem;
        padding-bottom: 1rem;
    }
}

Set up which breakpoints are available to USWDS utilities by setting the $theme-utility-breakpoints variable in your USWDS settings configuration.

Set whether a utility family outputs with responsive variants by setting the value of $[utility_family]-settings.responsive in your USWDS settings configuration. When modifying settings stored as a map, undefined map elements will keep their default values.

Example

@use "uswds-core" with (
  $background-color-settings: (
    responsive: true
  )
);

State Modifiers

Use a state prefix separated with a : to target a utility in a specific state.

Example

.hover:bg-primary-vivid

Output

.hover\:bg-primary-vivid:hover { background-color: #0052de; }

Set whether a utility outputs a specific state variant by setting the value of the $[utility_family]-settings.[state] variable in your USWDS settings configuration. When modifying settings stored as a map, undefined map elements will keep their default values.

Example

@use "uswds-core" with (
  $background-color-settings: (
    active: true
  )
);

Utilities Package, Settings, and Modules

USWDS provides a useful default set of utilities that developers can extend and modify in their project’s settings to suit their project’s needs and their development preferences.

Utilities are included by default as part of the uswds bundle package that most projects use. (Read more about packages here.)

If you unbundle your project’s packages, include utilities with the uswds-utilities package. This package includes all of the USWDS utilities available to the design system. Each utility is configured differently — some have responsive and state variants enabled. Each utility’s default output is documented on its documentation page.

The entire package is 198 KB uncompressed.

Include the uswds-utilities package in your project’s Sass entry point with a module forward:

@forward "uswds-utilities";

Settings

You can further customize utility output with USWDS settings. Add settings from the table below to your uswds-core module initialization. For more information on configuring USWDS settings, visit the settings page. Here’s an example:

@use 'uswds-core';
uswds-core.$output-these-utilities: (
    'padding',
    'box-shadow',
    'font',
    'background-color',
    'font-weight',
    'border-color',
    'line-height',
    'justify-content'
);
// Add aspect ALWAYS outputs no matter the settings. So let's make sure we get
// the smallest possible aspect classes.
uswds-core.$add-aspect-settings: (
    output: false,
    responsive: false,
    active: false,
    focus: false,
    hover: false,
    visited: false
);
uswds-core.$background-color-settings: (
    output: true,
    responsive: false,
    active: false,
    focus: false,
    hover: false,
    // Undo default
    visited: false
);
uswds-core.$box-shadow-settings: (
    output: true,
    responsive: false,
    active: false,
    focus: false,
    hover: false,
    // Undo default
    visited: false
);
uswds-core.$border-color-settings: (
    output: true,
    responsive: false,
    // Undo default
    active: false,
    focus: false,
    hover: false,
    // Undo default
    visited: false
);
uswds-core.$justify-content-settings: (
    output: true,
    responsive: true,
    // Undo default
    active: false,
    focus: false,
    hover: false,
    visited: false
);

@forward 'uswds-utilities';

Utility Modules