Utilities
Border
Set width, color, style, and radius of an item’s borders
CSS properties
Note: The border utilities apply a solid border of specified width. If no width is specified, the utilities apply a solid 1px border.
Border on all sides
Border on the top
Border on the bottom
Border on the left
Border on the right
Border on the left and right
Border on the top and bottom
Note: The border-width utilities apply only the border-width property to an item.
.border-transparent transparent
.border-black #000000
.border-white #ffffff
.border-base-lightest
gray-5
#f0f0f0
.border-base-lighter
gray-cool-10
#dfe1e2
.border-base-light
gray-cool-30
#a9aeb1
.border-base
gray-cool-50
#71767a
.border-base-dark
gray-cool-60
#565c65
.border-base-darker
gray-cool-70
#3d4551
.border-base-darkest
gray-90
#1b1b1b
.border-ink
gray-90
#1b1b1b
.border-primary-lighter
blue-10
#d9e8f6
.border-primary-light
blue-30
#73b3e7
.border-primary
blue-60v
#005ea2
.border-primary-vivid
blue-warm-60v
#0050d8
.border-primary-dark
blue-warm-70v
#1a4480
.border-primary-darker
blue-warm-80v
#162e51
.border-secondary-lighter
red-cool-10v
#f8dfe2
.border-secondary-light
red-30
#f2938c
.border-secondary
red-50
#d83933
.border-secondary-vivid
red-cool-50v
#e41d3d
.border-secondary-dark
red-60v
#b50909
.border-secondary-darker
red-70v
#8b0a03
.border-accent-cool-lighter
blue-cool-5v
#e1f3f8
.border-accent-cool-light
blue-cool-20v
#97d4ea
.border-accent-cool
cyan-30v
#00bde3
.border-accent-cool-dark
blue-cool-40v
#28a0cb
.border-accent-cool-darker
blue-cool-60v
#07648d
.border-accent-warm-lighter
orange-10
#f2e4d4
.border-accent-warm-light
orange-20v
#ffbc78
.border-accent-warm
orange-30v
#fa9441
.border-accent-warm-dark
orange-50v
#c05600
.border-accent-warm-darker
orange-60
#775540
.border-emergency
red-warm-60v
#9c3d10
.border-emergency-dark
red-warm-80
#332d29
.border-white #ffffff
.border-gray-5 #f0f0f0
.border-gray-10 #e6e6e6
.border-gray-30 #adadad
.border-gray-50 #757575
.border-gray-70 #454545
.border-gray-90 #171717
.border-black #000000
.border-red
red-50v
#e52207
.border-orange
orange-40v
#e66f0e
.border-gold
gold-20v
#ffbe2e
.border-yellow
yellow-10v
#fee685
.border-green
green-50v
#538200
.border-mint
mint-30v
#04c585
.border-cyan
cyan-40v
#009ec1
.border-blue
blue-50v
#0076d6
.border-indigo
indigo-50
#676cc8
.border-violet
violet-50
#8168b3
.border-magenta
magenta-50v
#d72d79
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 |
|---|---|---|
| .border-units | u-border(units) | @include u-border(2px) |
.border-modifier-units
|
u-border-modifier(units)
|
@include u-border-y(1) |
| .border-color | u-border(color) | @include u-border('primary-vivid') |
.border-style
|
u-border(modifier)
|
@include u-border('dotted') |
.radius-radius
|
u-radius(radius)
|
@include u-radius('sm') |
.radius-modifier-radius
|
u-radius-modifier(radius)
|
@include u-radius-left('pill') |
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-or.flex-) or a single utility accepts multiple kinds of values (ex:.borderaccepts both border weight and border color), their shared mixin can accept multiple comma-separated values:u-text('primary-darkest', 'no-underline', 'bold')oru-border-top(2px, 'accent-warm'). - Output any utility mixin as
!importantby appending!importantto 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 |
|---|---|
| $border-settings.responsive | true |
| $border-style-settings.responsive | true |
| $border-width-settings.responsive | true |
| $border-color-settings.responsive | true |
| $border-radius-settings.responsive | true |
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 |
|---|---|---|---|---|
| $border-settings | false | false | true | false |
| $border-style-settings | false | false | false | false |
| $border-width-settings | false | false | false | false |
| $border-color-settings | false | false | true | false |
| $border-radius-settings | false | false | false | 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 |
|---|---|
| $border-settings.output | true |
| $border-style-settings.output | true |
| $border-width-settings.output | true |
| $border-color-settings.output | true |
| $border-radius-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.
Example
$border-color-palettes: ( 'palette-color-blue-warm-medium-vivid' // note: no trailing comma );
Output
.border-blue-warm-40v { border-color: #5E99FF; }
.border-blue-warm-50v { border-color: #2673DF; }
.border-blue-warm-60v { border-color: #0052DE; }
Default palettes
| Palette name | Palette contents |
|---|---|
| 'palette-border-default' | border default tokens |
| 'palette-border-style-default' | border-style default tokens |
| 'palette-border-width-default' | border-width default tokens |
| 'palette-border-color-default' | border-color default tokens |
| 'palette-border-radius-default' | border-radius default tokens |
Spacing and units
| Palette name | Palette contents |
|---|---|
| 'palette-units' | All spacing unit tokens (system, ch, em, percentage) |
| 'palette-units-system' | All system spacing unit tokens |
| 'palette-units-system-breakpoints' | All named spacing unit tokens: card, card-lg, mobile, mobile-lg, tablet, tablet-lg, desktop, desktop-lg, widescreen |
| 'palette-units-system-positive' | All positive spacing unit tokens |
| 'palette-units-system-positive-smaller' | 1px, 2px |
| 'palette-units-system-positive-small' | 05, 1, 105, 2, 205, 3 |
| 'palette-units-system-positive-medium' | 4, 5, 6, 7, 8, 9, 10, 15 |
| 'palette-units-system-positive-large' | card, card-lg, mobile |
| 'palette-units-system-positive-larger' | mobile-lg, tablet, tablet-lg |
| 'palette-units-system-positive-largest' | desktop, desktop-lg, widescreen |
| 'palette-units-system-negative' | All negative spacing values |
| 'palette-units-system-negative-smaller' | neg-1px, neg-2px |
| 'palette-units-system-negative-small' | neg-05, neg-1, neg-105, neg-2, neg-205, neg-3 |
| 'palette-units-ch' | 05ch, 1ch, 105ch, 2ch, 3ch, 4ch, 5ch, neg-05ch, neg-1ch, neg-105ch, neg-2ch, neg-3ch, neg-4ch, neg-5ch |
| 'palette-units-ch-positive' | 05ch, 1ch, 105ch, 2ch, 3ch, 4ch, 5ch |
| 'palette-units-ch-negative' | neg-05ch, neg-1ch, neg-105ch, neg-2ch, neg-3ch, neg-4ch, neg-5ch |
| 'palette-units-em' | 05em, 1em, 105em, 2em, 3em, 4em, 5em, 6em, 7em, 8em, 9em, 10em |
| 'palette-units-percentage' | 10ct, 20ct, 25ct, 30ct, 33ct, 40ct, 50ct, 60ct, 66ct, 75ct, 80ct, 90ct, 100ct |
| 'palette-units-0' | 0 |
Color palettes
In the following table, family indicates a specific unquoted system color family token (like blue-warm) as documented on the system color tokens page.
| Palette name | Palette contents |
|---|---|
| 'palette-color' | All color tokens |
| 'palette-color-default' | System default color tokens |
| 'palette-color-theme' | All theme color tokens |
| 'palette-color-state' | All state color tokens |
| 'palette-color-grayscale' | gray-5, gray-10, gray-30, gray-50, gray-70, gray-90 |
| 'palette-color-basic' | All basic colors |
| 'palette-color-system' | All grades in all system color tokens |
| 'palette-color-system-family' | All grades in the specified family |
| 'palette-color-system-family-light' | Grades 5, 10, 20, 30 |
| 'palette-color-system-family-light-vivid' | Grades 5v, 10v, 20v, 30v |
| 'palette-color-system-family-medium' | Grades 40, 50, 60 |
| 'palette-color-system-family-medium-vivid' | Grades 40v, 50v, 60v |
| 'palette-color-system-family-dark' | Grades 70, 80, 90 |
| 'palette-color-system-family-dark-vivid' | Grades 70v, 80v, 90v |
| 'palette-color-system-family-standard' | Grades 5, 10, 20, 30, 40, 50, 60, 70, 80, 90 |
| 'palette-color-system-family-vivid' | Grades 5v, 10v, 20v, 30v, 40v, 50v, 60v, 70v, 80v, 90v |
