Utilities

Border

Set width, color, style, and radius of an item’s borders

CSS properties

border border-style border-width border-color border-radius

Examples and usage

Utilities, values, and variants may be activated and deactivated in advanced settings.

Border

CSS property: border, border-bottom, border-left, border-right, border-top

Note: The border utilities apply a solid border of specified width. If no width is specified, the utilities apply a solid 1px border.

.border
.border-top
.border-bottom
.border-left
.border-right
.border-x
.border-y

Border on all sides

.border
1px
.border-0
0
.border-1px
1px
.border-2px
2px
.border-05
4px
.border-1
8px
.border-105
12px
.border-2
16px
.border-205
20px
.border-3
24px

Border on the top

.border-top
1px
.border-top-0
0
.border-top-1px
1px
.border-top-2px
2px
.border-top-05
4px
.border-top-1
8px
.border-top-105
12px
.border-top-2
16px
.border-top-205
20px
.border-top-3
24px

Border on the bottom

.border-bottom
1px
.border-bottom-0
0
.border-bottom-1px
1px
.border-bottom-2px
2px
.border-bottom-05
4px
.border-bottom-1
8px
.border-bottom-105
12px
.border-bottom-2
16px
.border-bottom-205
20px
.border-bottom-3
24px

Border on the left

.border-left
1px
.border-left-0
0
.border-left-1px
1px
.border-left-2px
2px
.border-left-05
4px
.border-left-1
8px
.border-left-105
12px
.border-left-2
16px
.border-left-205
20px
.border-left-3
24px

Border on the right

.border-right
1px
.border-right-0
0
.border-right-1px
1px
.border-right-2px
2px
.border-right-05
4px
.border-right-1
8px
.border-right-105
12px
.border-right-2
16px
.border-right-205
20px
.border-right-3
24px

Border on the left and right

.border-x
1px
.border-x-0
0
.border-x-1px
1px
.border-x-2px
2px
.border-x-05
4px
.border-x-1
8px
.border-x-105
12px
.border-x-2
16px
.border-x-205
20px
.border-x-3
24px

Border on the top and bottom

.border-y
1px
.border-y-0
0
.border-y-1px
1px
.border-y-2px
2px
.border-y-05
4px
.border-y-1
8px
.border-y-105
12px
.border-y-2
16px
.border-y-205
20px
.border-y-3
24px

Border style

CSS property: border-style

.border.border-solid
.border.border-dashed
.border.border-dotted

Border width

CSS property: border-width

Note: The border-width utilities apply only the border-width property to an item.

.border-width-0 0
.border-width-1px 1px
.border-width-2px 2px
.border-width-05 4px
.border-width-1 8px
.border-width-105 12px
.border-width-2 16px
.border-width-205 20px
.border-width-3 24px
.border-top-width-0 0
.border-top-width-1px 1px
.border-top-width-2px 2px
.border-top-width-05 4px
.border-top-width-1 8px
.border-top-width-105 12px
.border-top-width-2 16px
.border-top-width-205 20px
.border-top-width-3 24px
.border-bottom-width-0 0
.border-bottom-width-1px 1px
.border-bottom-width-2px 2px
.border-bottom-width-05 4px
.border-bottom-width-1 8px
.border-bottom-width-105 12px
.border-bottom-width-2 16px
.border-bottom-width-205 20px
.border-bottom-width-3 24px
.border-left-width-0 0
.border-left-width-1px 1px
.border-left-width-2px 2px
.border-left-width-05 4px
.border-left-width-1 8px
.border-left-width-105 12px
.border-left-width-2 16px
.border-left-width-205 20px
.border-left-width-3 24px
.border-right-width-0 0
.border-right-width-1px 1px
.border-right-width-2px 2px
.border-right-width-05 4px
.border-right-width-1 8px
.border-right-width-105 12px
.border-right-width-2 16px
.border-right-width-205 20px
.border-right-width-3 24px
.border-x-width-0 0
.border-x-width-1px 1px
.border-x-width-2px 2px
.border-x-width-05 4px
.border-x-width-1 8px
.border-x-width-105 12px
.border-x-width-2 16px
.border-x-width-205 20px
.border-x-width-3 24px
.border-y-width-0 0
.border-y-width-1px 1px
.border-y-width-2px 2px
.border-y-width-05 4px
.border-y-width-1 8px
.border-y-width-105 12px
.border-y-width-2 16px
.border-y-width-205 20px
.border-y-width-3 24px

Border color

CSS property: border-color

.border-transparent

.border-black

.border-white

.border-base-lightest

.border-base-lighter

.border-base-light

.border-base

.border-base-dark

.border-base-darker

.border-base-darkest

.border-ink

.border-primary-lighter

.border-primary-light

.border-primary

.border-primary-vivid

.border-primary-dark

.border-primary-darker

.border-secondary-lighter

.border-secondary-light

.border-secondary

.border-secondary-vivid

.border-secondary-dark

.border-secondary-darker

.border-accent-cool-lighter

.border-accent-cool-light

.border-accent-cool

.border-accent-cool-dark

.border-accent-cool-darker

.border-accent-warm-lighter

.border-accent-warm-light

.border-accent-warm

.border-accent-warm-dark

.border-accent-warm-darker

.border-white

.border-gray-5

.border-gray-10

.border-gray-30

.border-gray-50

.border-gray-70

.border-gray-90

.border-black

.border-red

.border-orange

.border-gold

.border-yellow

.border-green

.border-mint

.border-cyan

.border-blue

.border-indigo

.border-violet

.border-magenta

Border radius

CSS property: border-radius

.radius-0
0
.radius-sm
2px
.radius-md
4px
.radius-lg
8px
.radius-pill
99rem
.radius-top-0
0
.radius-top-sm
2px
.radius-top-md
4px
.radius-top-lg
8px
.radius-top-pill
99rem
.radius-bottom-0
0
.radius-bottom-sm
2px
.radius-bottom-md
4px
.radius-bottom-lg
8px
.radius-bottom-pill
99rem
.radius-left-0
0
.radius-left-sm
2px
.radius-left-md
4px
.radius-left-lg
8px
.radius-left-pill
99rem
.radius-right-0
0
.radius-right-sm
2px
.radius-right-md
4px
.radius-right-lg
8px
.radius-right-pill
99rem

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 (like neg-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: .border accepts both border weight and border color), their shared mixin can accept multiple comma-separated values: u-text('primary-darkest', 'no-underline', 'bold') or u-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.

Set which breakpoints are available to USWDS utilities with the $theme_output_breakpoints variable found in _uswds-theme-utilities.scss.

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 _uswds-theme-utilities.scss.

Utility variable Default
$border-settings.responsive true
$border-style-settings.responsive false
$border-width-settings.responsive false
$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.

Set whether a utility outputs a specific state variant by setting the value of the $[utility_family]-settings.[state] variable in _uswds-theme-utilities.scss.

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 found in _uswds-theme-utilities.scss.

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 documentation above. Customize and refine any utility family’s specific values by editing the $[utility_family]-manual-values and $[utility_family]-palettes variables in _uswds-theme-utilities.scss.

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.

Palettes

Palettes are predefined groups of values. Add palettes to the $[utility_family]-palettes list variable in _uswds-theme-utilities.scss to add those values to the utility family.

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