Utilities
Shadow
Set size of an item’s drop shadow
CSS properties
Utility mixins
Utilities may be used in component Sass with utility mixins. Highlighted tokens are the USWDS design tokens that serve as the foundation for all design system styles. Each token is also a documentation link. Consult the Design tokens section for more information on tokens and how to use them in USWDS.
Utility | Mixin | Example |
---|---|---|
.shadow-shadow | u-shadow(shadow) | @include u-shadow(2) |
Using utility mixins
- Use single-quoted strings in utility mixins. Do not quote numbers or px values, with the exception of half (
05
) values like'05'
,'105'
, and'205'
which should be treated as strings. - String tokens for half values (
05
) and negative values (likeneg-1
)may also be written with their unquoted number token equivalent:0.5
,1.5
,2.5
,2.5
,-1
,-1.5
, etc - If multiple utilities share the same prefix (ex:
.text-
oder.flex-
) or a single utility accepts multiple kinds of values (ex:.border
accepts both border weight and border color), their shared mixin can accept multiple comma-separated values:u-text('primary-darkest', 'no-underline', 'bold')
oderu-border-top(2px, 'accent-warm')
. - Output any utility mixin as
!important
by appending!important
to the mixin’s argument list:u-bg('red-warm-50v', !important)
.
Advanced settings
Responsive variants
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.
Breakpoint name | Width | Default |
---|---|---|
card | 160px | false |
card-lg | 240px | false |
mobile | 320px | false |
mobile-lg | 480px | true |
tablet | 640px | true |
tablet-lg | 880px | false |
desktop | 1024px | true |
desktop-lg | 1200px | false |
widescreen | 1400px | false |
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 ) );
Utility variable | Default |
---|---|
$box-shadow-settings.responsive | false |
State variants
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 ) );
Utility variable | active | focus | hover | visited |
---|---|---|---|---|
$box-shadow-settings | false | false | true | false |
Output control
Control whether or not to output any USWDS utility family by setting the value of the $[utility_family]-settings.output
variable in your USWDS settings configuration.
A value of true
will output the utility family and any variants. A value of false
prevents the output of the family and any variants.
Utility variable | Default |
---|---|
$box-shadow-settings.output | true |
Custom values
By default, USWDS utilities output the standard values listed in the standard output table. Customize and refine any utility family’s specific values by editing the $[utility_family]-manual-values
and $[utility_family]-palettes
variables in your USWDS settings configuration.
Manual values
Specify manual values as unique key:value
pairs using the $[utility_family]-manual-values
map, where the key
is the utility’s value suffix, and the value
is what the utility will output.
Example
$width-manual-values: ( 'tab': 4ch, );
Output
.width-tab { width: 4ch; }
Palettes
Palettes are predefined groups of values. Add palettes to the $[utility_family]-palettes
list variable in your USWDS settings configuration to add those values to the utility family.
There are no custom palettes associated with this utility.