Utilities

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.

Introducing utilities

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.)

USWDS utility	Sass
.bg-primary-darker	background-color: color('primary-darker')
.bg-red-50v	background-color: color('red-50v')
.text-underline	text-decoration: underline
.margin-x-auto	margin-left: auto; margin-right: auto;
.padding-bottom-1	padding-bottom: units(1)

Utilities package, modules, and settings

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" with (
  $utilities-use-important: true,
  $output-these-utilities:(
    "background-color",
    "color",
    "display",
    "margin",
    "padding",
  ),
  $theme-utility-breakpoints: (
    "mobile-lg": false,
  ),
  $color-settings: (
    "hover": false,
  ),
  $color-palettes: (
    "palette-color-theme"
  ),
);

Name	Variable	Default	Type	Description
Utilities use !important	$utilities-use-important	false	boolean	Output all utilities with !important. This can be necessary if you intend utilities to override existing styles.
Utilities uselist	$output-these-utilities	default	list	Include a list of all utility modules to output. Ex: ("align-items", "border", "margin", "padding"). default includes all utilities.
Utility breakpoints	$theme-utility-breakpoints		map	Set which mobile-first breakpoints are output for the utilities.
Utility breakpoints	"card"	false	boolean
Utility breakpoints	"card-lg"	false	boolean
Utility breakpoints	"mobile"	false	boolean
Utility breakpoints	"mobile-lg"	true	boolean
Utility breakpoints	"tablet"	true	boolean
Utility breakpoints	"tablet-lg"	false	boolean
Utility breakpoints	"desktop"	true	boolean
Utility breakpoints	"desktop-lg"	false	boolean
Utility breakpoints	"widescreen"	false	boolean
Custom breakpoints	$theme-utility-breakpoints-custom		map	Set additional custom mobile-first breakpoints to be output for the utilities. Values must be passed in with px values inside a Sass map.
Global color palettes	$global-color-palettes		palettes	Any palettes added to this list will output in the the following utilities: background-color, border-color, color, text-decoration-color.
Utility settings	$[utility-module]-settings		map	Control the output of a [utility-module] and its responsive and state variants.
Utility settings	"output"	—	boolean	Output the utility.
Utility settings	"responsive"	—	boolean	Output the responsive variants.
Utility settings	"active"	—	boolean	Output the active: state variant.
Utility settings	"focus"	—	boolean	Output the focus: state variant.
Utility settings	"hover"	—	boolean	Output the hover: state variant.
Utility settings	"visited"	—	boolean	Output the visited: state variant.
Utility palettes	$[utility-module]-palettes	"palette-[utility-module]-default"	palettes	Utilities output with the values set in the palettes list.
Utility manual values	$[utility-module]-manual-values		map	Utilities output with the tokens and values set in the manual values map.
Utility manual values	[token name]	[token value]	map	Add a map of manual tokens and values in the form name: value.

Modules

Each utility module referenced in the settings section, above, can accept one of the utility module names outlined in the following table. The more utilities your project uses, the larger the utilities CSS will be.

The size of each module will change based on its module settings. For instance, if a module is set to output responsive classes and state variants, it will be much larger than if it includes only the base classes and no variants.

Utility module name	Class base	Gzip size	Default full size
add-aspect	add-aspect-	0.08 KB	0.44 KB
add-list-reset	add-list-reset	0.02 KB	0.12 KB
align-items	flex-	0.04 KB	0.24 KB
align-self	flex-	0.06 KB	0.31 KB
background-color	bg-	1.0 KB	5.4 KB
border	border-	4.35 KB	23.5 KB
border-color	border-	4.35 KB	23.5 KB
border-radius	border-	1.61 KB	8.7 KB
border-style	border-	0.03 KB	0.14 KB
border-width	border-	0.56 KB	3 KB
bottom	bottom-	0.18 KB	0.96 KB
box-shadow	shadow-	0.06 KB	0.33 KB
circle	circle-	0.19 KB	1 KB
clearfix	clearfix	0.02 KB	0.09 KB
color	text-	0.37 KB	2 KB
cursor	cursor-	0.07 KB	0.39 KB
display	display-	0.28 KB	1.5 KB
flex	flex-	0.06 KB	0.33 KB
flex-direction	flex-	0.02 KB	0.1 KB
flex-wrap	flex-	0.02 KB	0.1 KB
float	float-	0.02 KB	0.1 KB
font	font-	2.41 KB	13 KB
font-family	font-family-	0.37 KB	2 KB
font-feature	text-	0.03 KB	0.14 KB
font-style	text-	0.02 KB	0.11 KB
font-weight	text-	0.1 KB	0.54 KB
height	height-	0.11 KB	0.6 KB
justify-content	flex-	0.18 KB	0.95 KB
left	left-	0.08 KB	0.44 KB
letter-spacing	text-ls-	0.05 KB	0.28 KB
line-height	line-height-	1.61 KB	8.7 KB
margin	margin-	0.8 KB	4.35 KB
margin-horizontal	margin-	4.02 KB	21.75 KB
margin-vertical	margin-	4.02 KB	21.75 KB
max-height	maxh-	0.12 KB	0.65 KB
max-width	maxw-	0.13 KB	0.72 KB
measure	measure-	0.18 KB	0.98 KB
min-height	minh-	0.13 KB	0.72 KB
min-width	minw-	0.07 KB	0.4 KB
opacity	opacity-	0.24 KB	1.3 KB
order	order-	0.26 KB	1.4 KB
outline	outline-	0.03 KB	0.18 KB
outline-color	outline-	0.56 KB	3 KB
overflow	overflow-	0.09 KB	0.46 KB
padding	padding-	4.02 KB	21.75 KB
pin	pin-	0.06 KB	0.35 KB
position	position-	0.04 KB	0.21 KB
right	right-	0.09 KB	0.47 KB
square	square-	0.14 KB	0.73 KB
text-align	text-	0.03 KB	0.16 KB
text-decoration	underline-	0.06 KB	0.32 KB
text-decoration-color	text-	2.33 KB	12.6 KB
text-indent	text-indent-	0.19 KB	1 KB
text-transform	text-	0.04 KB	0.2 KB
top	top-	0.07 KB	0.4 KB
vertical-align	text-	0.06 KB	0.32 KB
whitespace	text-	0.04 KB	0.2 KB
width	width-	0.56 KB	3 KB
z-index	z-	0.04 KB	0.22 KB

Latest updates

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

Date	USWDS version	Affects	Breaking	Description
2024-06-26	N/A	Guidance	No	Fixed example in settings. Added missing comma to color example in $output-these-utilities. More information: uswds-site#2731
2023-06-09	3.5.0	Styles	No	Removed unused utility builder comments from compiled CSS. This update significantly reduces the compiled file size. More information: uswds#5209
2023-06-09	3.5.0	Guidance Styles	Breaking	Breaking Updated sass map instructions to reflect new pattern. Users are now instructed to define only the variable they wish to change instead of having to define the entire map. More information: uswds#5216
2023-03-09	3.4.0	Guidance Styles	No	Outline utility and mixin now accept the 05 token. Now, the .outline-05 utility class and the u-outline('05') mixin should work as expected. More information: uswds#5079
2022-05-04	N/A	Guidance	No	Added margin-horizontal and margin-vertical utility modules. More information: uswds-site#1583
2022-04-28	3.0.0	Styles	No	Replaced the outdated text: $output-all-utilities with updated: $output-these-utilities. More information: uswds#4631
2022-04-28	N/A	Guidance	No	Added documentation for using the uswds-utilities package, customizing utilities settings, and understanding utility modules. More information: uswds-site#1538
2021-06-16	2.12.0	Styles	No	Added state color tokens to default utilities. More information: uswds#4198