Utilities

Display

Control the position and display characteristics of an item

CSS properties

bottom display left opacity overflow position right top z-index

Examples and usage

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

Display

CSS property: display

.display-block
block
.display-flex
flex
.display-inline
inline
.display-inline-block
inline-block
.display-inline-flex
inline-flex
.display-none
none
.display-table-cell
table-cell
1
2
3
4
5
6
7
8
9
10
11
12
<div class="display-block border-1px ...">.display-block</div>
<div class="display-flex border-1px ...">.display-flex</div>
<div class="display-inline border-1px ...">.display-inline</div>
<div class="display-inline-block border-1px ...">.display-inline-block</div>
<div class="display-inline-flex border-1px ...">.display-inline-flex</div>
<div class="display-none ...">.display-none</div>
<div class="display-table">
  <div class="display-table-row">
    <div class="display-table-cell border-1px ...">.display-table-cell</div>
    <div class="display-table-cell border-1px ...">.display-table-cell</div>
  </div>
</div>

Opacity

CSS property: opacity

  • responsive
  • active
  • hover
  • focus
  • visited
.opacity-0
0
.opacity-10
0.1
.opacity-20
0.2
.opacity-30
0.3
.opacity-40
0.4
.opacity-50
0.5
.opacity-60
0.6
.opacity-70
0.7
.opacity-80
0.8
.opacity-90
0.9
.opacity-100
1

Overflow

CSS property: overflow

  • responsive
  • active
  • hover
  • focus
  • visited

Note: Per the W3C overflow spec: The computed values of ‘overflow-x’ and ‘overflow-y’ are the same as their specified values, except that some combinations with ‘visible’ are not possible: if one is specified as ‘visible’ and the other is ‘scroll’ or ‘auto’, then ‘visible’ is set to ‘auto’. The computed value of ‘overflow’ is equal to the computed value of ‘overflow-x’ if ‘overflow-y’ is the same; otherwise it is the pair of computed values of ‘overflow-x’ and ‘overflow-y’.

Any element that includes scrollable content must also be selectable with the keyboard. Add a tabindex="0" property to elements that include scrollable content.

.overflow-visible
visible
.overflow-x-visible
visible
.overflow-y-visible
visible
.overflow-hidden
hidden
.overflow-x-hidden
hidden
.overflow-y-hidden
hidden
.overflow-scroll
scroll
.overflow-x-scroll
scroll
.overflow-y-scroll
scroll
.overflow-auto
auto
.overflow-x-auto
auto
.overflow-y-auto
auto

Position

CSS property: position

  • responsive
  • active
  • hover
  • focus
  • visited

.position-absolute

.position-fixed

.position-relative

.position-static

.position-sticky

Example: Relative, static, and absolute positioning

.position-static

.position-absolute

.position-relative

.position-absolute

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<div class="position-relative">
  <div class="position-static">
    <div class="position-absolute bottom-0 left-0">
      .position-absolute
    </div>
  </div>
</div>

<div class="position-relative">
  <div class="position-relative">
    <div class="position-absolute bottom-0 left-0">
      .position-absolute
    </div>
  </div>
</div>

Example: Fixed positioning

.position-fixed

Scroll me!

In compliance with the request of a friend of mine, who wrote me from the East, I called on good-natured, garrulous old Simon Wheeler, and inquired after my friend's friend, Leonidas W. Smiley, as requested to do, and I hereunto append the result.

I found Simon Wheeler dozing comfortably by the bar-room stove of the old, dilapidated tavern in the ancient mining camp of Angel's, and I noticed that he was fat and bald-headed, and had an expression of winning gentleness and simplicity upon his tranquil countenance. He roused up and gave me good-day. I told him a friend of mine had commissioned me to make some inquiries about a cherished companion of his boyhood named Leonidas W. Smiley Rev. Leonidas W. Smiley a young minister of the Gospel, who he had heard was at one time a resident of Angel's Camp. I added that, if Mr. Wheeler could tell me any thing about this Rev. Leonidas W. Smiley, I would feel under many obligations to him.

Simon Wheeler backed me into a corner and blockaded me there with his chair, and then sat me down and reeled off the monotonous narrative which follows this paragraph. He never smiled, he never frowned, he never changed his voice from the gentle-flowing key to which he tuned the initial sentence, he never betrayed the slightest suspicion of enthusiasm; but all through the interminable narrative there ran a vein of impressive earnestness and sincerity, which showed me plainly that, so far from his imagining that there was any thing ridiculous or funny about his story, he regarded it as a really important matter, and admired its two heroes as men of transcendent genius in finesse. To me, the spectacle of a man drifting serenely along through such a queer yarn without ever smiling, was exquisitely absurd. As I said before, I asked him to tell me what he knew of Rev. Leonidas W. Smiley, and he replied as follows. I let him go on in his own way, and never interrupted him once:

There was a feller here once by the name of Jim Smiley, in the winter of '49 or may be it was the spring of '50 I don't recollect exactly, somehow, though what makes me think it was one or the other is because I remember the big flume wasn't finished when he first came to the camp; but any way, he was the curiosest man about always betting on any thing that turned up you ever see, if he could get any body to bet on the other side; and if he couldn't, he'd change sides. Any way that suited the other man would suit him any way just so's he got a bet, he was satisfied. But still he was lucky, uncommon lucky; he most always come out winner. He was always ready and laying for a chance; there couldn't be no solittry thing mentioned but that feller'd offer to bet on it, and -take any side you please, as I was just telling you. If there was a horse-race, you'd find him flush, or you'd find him busted at the end of it; if there was a dog-fight, he'd bet on it; if there was a cat-fight, he'd bet on it; if there was a chicken-fight, he'd bet on it; why, if there was two birds setting on a fence, he would bet you which one would fly first; or if there was a camp-meeting, he would be there reg'lar, to bet on Parson Walker, which he judged to be the best exhorter about here, and so he was, too, and a good man. If he even seen a straddle-bug start to go anywheres, he would bet you how long it would take him to get wherever he was going to, and if you took him up, he would foller that straddle-bug to Mexico but what he would find out where he was bound for and how long he was on the road. Lots of the boys here has seen that Smiley, and can tell you about him. Why, it never made no difference to him he would bet on any thing the dangdest feller. Parson Walker's wife laid very sick once, for a good while, and it seemed as if they warn's going to save her; but one morning he come in, and Smiley asked how she was, and he said she was considerable better thank the Lord for his inftnit mercy and coming on so smart that, with the blessing of Providence, she'd get well yet; and Smiley, before he thought, says, "Well, I'll risk two- and-a-half that she don't, any way."

1
2
3
4
5
<div class="position-relative">
  <div class="position-fixed pin-top bg-secondary-light">
    .position-fixed
  </div>
</div>

Example: Sticky positioning

Sticky Heading 1 .position-sticky

Scroll me!

Thish-yer Smiley had a mare the boys called her the fifteen- minute nag, but that was only in fun, you know, because, of course, she was faster than that and he used to win money on that horse, for all she was so slow and always had the asthma, or the distemper, or the consumption, or something of that kind. They used to give her two or three hundred yards start, and then pass her under way; but always at the fag-end of the race she'd get excited and desperate- like, and come cavorting and straddling up, and scattering her legs around limber, sometimes in the air, and sometimes out to one side amongst the fences, and kicking up m-o-r-e dust, and raising m-o-r-e racket with her coughing and sneezing and blowing her nose and always fetch up at the stand just about a neck ahead, as near as you could cipher it down.

Sticky Heading 2 .position-sticky

And he had a little small bull pup, that to look at him you'd think he wan's worth a cent, but to set around and look ornery, and lay for a chance to steal something. But as soon as money was up on him, he was a different dog; his underjaw'd begin to stick out like the fo'castle of a steamboat, and his teeth would uncover, and shine savage like the furnaces. And a dog might tackle him, and bully- rag him, and bite him, and throw him over his shoulder two or three times, and Andrew Jackson which was the name of the pup Andrew Jackson would never let on but what he was satisfied, and hadn't expected nothing else and the bets being doubled and doubled on the other side all the time, till the money was all up; and then all of a sudden he would grab that other dog jest by the j'int of his hind leg and freeze on it not chew, you understand, but only jest grip and hang on till they thronged up the sponge, if it was a year. Smiley always come out winner on that pup, till he harnessed a dog once that didn't have no hind legs, because they'd been sawed off by a circular saw, and when the thing had gone along far enough, and the money was all up, and he come to make a snatch for his pet bolt, he saw in a minute how he'd been imposed on, and how the other dog had him in the door, so to speak, and he 'peered sur- prised, and then he looked sorter discouraged-like, and didn't try no more to win the fight, and so he got shucked out bad. He give Smiley a look, as much as to say his heart was broke, and it was his fault, for putting up a dog that hadn't no hind legs for him to take bolt of, which was his main dependence in a fight, and then he limped off a piece and laid down and died. It was a good pup, was that Andrew Jackson, and would have made a name for hisself if he'd lived, for the stuff was in him, and he had genius I know it, because he hadn't had no opportunities to speak of, and it don't stand to reason that a dog could make such a fight as he could under them circumstances, if he hadn't no talent. It always makes me feel sorry when I think of that last fight of his'n, and the way it turned out.

Sticky Heading 3 .position-sticky

Well, thish-yer Smiley had rat-tarriers, and chicken cocks, and tom- cats, and all of them kind of things, till you couldn't rest, and you couldn't fetch nothing for him to bet on but he'd match you. He ketched a frog one day, and took him home, and said he cal'klated to edercate him; and so he never done nothing for three months but set in his back yard and learn that frog to jump. And you bet you he did learn him, too. He'd give him a little punch behind, and the next minute you'd see that frog whirling in the air like a doughnut see him turn one summerset, or may be a couple, if he got a good start, and come down flat-footed and all right, like a cat. He got him up so in the matter of catching flies, and kept him in practice so constant, that he'd nail a fly every time as far as he could see him. Smiley said all a frog wanted was education, and he could do most any thing and I believe him. Why, I've seen him set Dan'l Webster down here on this floor Dan'l Webster was the name of the frog and sing out, "Flies, Dan'l, flies!" and quicker'n you could wink, he'd spring straight up, and snake a fly off'n the counter there, and flop down on the floor again as solid as a gob of mud, and fall to scratching the side of his head with his hind foot as indifferent as if he hadn't no idea he'd been doin' any more'n any frog might do. You never see a frog so modest and straightforward as he was, for all he was so gifted. And when it come to fair and square jumping on a dead level, he could get over more ground at one straddle than any animal of his breed you ever see. Jumping on a dead level was his strong suit, you understand; and when it come to that, Smiley would ante up money on him as long as he had a red. Smiley was monstrous proud of his frog, and well he might be, for fellers that had traveled and been everywheres, all said he laid over any frog that ever they see.

Sticky Heading 4 .position-sticky

Well, Smiley kept the beast in a little lattice box, and he used to fetch him down town sometimes and lay for a bet. One day a feller a stranger in the camp, he was come across him with his box, and says:

"What might it be that you've got in the box?"

And Smiley says, sorter indifferent like, "It might be a parrot, or it might be a canary, may be, but it an't it's only just a frog."

And the feller took it, and looked at it careful, and turned it round this way and that, and says, "H'm so 'tis. Well, what's he good for?"

"Well," Smiley says, easy and careless, "He's good enough for one thing, I should judge he can outjump any frog in Calaveras county."

The feller took the box again, and took another long, particular look, and give it back to Smiley, and says, very deliberate, "Well, I don't see no p'ints about that frog that's any better'n any other frog."

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<div class="position-relative overflow-scroll">
  <div>
    <div class="position-sticky bg-secondary-light">Sticky Heading 1</div>
    <p>...</p>
  </div>
  <div>
    <div class="position-sticky bg-gold">Sticky Heading 2</div>
    <p>...</p>
  </div>
  <div>
    <div class="position-sticky bg-yellow">Sticky Heading 3</div>
    <p>...</p>
  </div>
  <div>
    <div class="position-sticky bg-orange">Sticky Heading 4</div>
    <p>...</p>
  </div>
</div>

Relative position

CSS property: top, bottom, left, right

  • responsive
  • active
  • hover
  • focus
  • visited
.top-auto
auto
.top-neg-3
-24px
.top-neg-205
-20px
.top-neg-2
-16px
.top-neg-105
-12px
.top-neg-1
-8px
.top-neg-05
-4px
.top-neg-2px
-2px
.top-neg-1px
-1px
.top-0
0
.top-1px
1px
.top-2px
2px
.top-05
4px
.top-1
8px
.top-105
12px
.top-2
16px
.top-205
20px
.top-3
24px
.top-full
100%
.right-auto
auto
.right-neg-3
-24px
.right-neg-205
-20px
.right-neg-2
-16px
.right-neg-105
-12px
.right-neg-1
-8px
.right-neg-05
-4px
.right-neg-2px
-2px
.right-neg-1px
-1px
.right-0
0
.right-1px
1px
.right-2px
2px
.right-05
4px
.right-1
8px
.right-105
12px
.right-2
16px
.right-205
20px
.right-3
24px
.right-full
100%
.bottom-auto
auto
.bottom-neg-3
-24px
.bottom-neg-205
-20px
.bottom-neg-2
-16px
.bottom-neg-105
-12px
.bottom-neg-1
-8px
.bottom-neg-05
-4px
.bottom-neg-2px
-2px
.bottom-neg-1px
-1px
.bottom-0
0
.bottom-1px
1px
.bottom-2px
2px
.bottom-05
4px
.bottom-1
8px
.bottom-105
12px
.bottom-2
16px
.bottom-205
20px
.bottom-3
24px
.bottom-full
100%
.left-auto
auto
.left-neg-3
-24px
.left-neg-205
-20px
.left-neg-2
-16px
.left-neg-105
-12px
.left-neg-1
-8px
.left-neg-05
-4px
.left-neg-2px
-2px
.left-neg-1px
-1px
.left-0
0
.left-1px
1px
.left-2px
2px
.left-05
4px
.left-1
8px
.left-105
12px
.left-2
16px
.left-205
20px
.left-3
24px
.left-full
100%

Pin

  • responsive
  • active
  • hover
  • focus
  • visited

The pin utilities position an item absolutely to the specified side.

.pin-top
.pin-bottom
.pin-left
.pin-right
.pin-x
.pin-y
.pin-all
.pin-none
.pin-top.pin-x
.pin-bottom.pin-x
.pin-left.pin-y
.pin-right.pin-y

Z-index

CSS property: z-index

  • responsive
  • active
  • hover
  • focus
  • visited
.z-auto auto
.z-top 99999
.z-500 500
.z-400 400
.z-300 300
.z-200 200
.z-100 400
.z-0 0
.z-bottom -100

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
.display-value u-display(value) @include u-display('block')
.opacity-opacity u-opacity(opacity) @include u-opacity(0)
.overflow-modifier-value u-overflow-modifier(value) @include u-overflow-x('hidden')
.position-value u-position(value) @include u-position('relative')
.bottom-units u-bottom(units) @include u-bottom('auto')
.left-units u-left(units) @include u-left(-2px)
.right-units u-right(units) @include u-right('full')
.top-units u-top(units) @include u-top('05')
.pin-value u-pin-value @include u-pin-x

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.

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
$display-settings.responsive true
$opacity-settings.responsive false
$overflow-settings.responsive false
$position-settings.responsive false
$bottom-settings.responsive false
$left-settings.responsive false
$right-settings.responsive false
$top-settings.responsive false
$pin-settings.responsive false
$z-index-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
$display-settings false false false false
$opacity-settings false false false false
$overflow-settings false false false false
$position-settings false false false false
$bottom-settings false false false false
$left-settings false false false false
$right-settings false false false false
$top-settings false false false false
$pin-settings false false false false
$z-index-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
$display-settings.output true
$opacity-settings.output true
$overflow-settings.output true
$position-settings.output true
$bottom-settings.output true
$left-settings.output true
$right-settings.output true
$top-settings.output true
$pin-settings.output true
$z-index-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

$top-palettes: (
  'palette-units-system-smaller',
  'palette-units-system-smaller-negative', // note: no trailing comma
);

Output

.top-1px     { margin: 1px; }
.top-2px     { margin: 2px; }
.top-neg-1px { margin: -1px; }
.top-neg-2px { margin: -2px; }

Default palettes

Palette name Palette contents
'palette-display-default' display default tokens
'palette-opacity-default' opacity default tokens
'palette-overflow-default' overflow default tokens
'palette-position-default' position default tokens
'palette-bottom-default' bottom default tokens
'palette-left-default' left default tokens
'palette-right-default' right default tokens
'palette-top-default' top default tokens
'palette-pin-default' pin default tokens
'palette-z-index-default' z-index 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

Latest updates

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

Date USWDS version Affects Breaking Description
2023-12-08 3.7.1
  • Styles
No

Fixed a bug that prevented the CSS from generating .left-full, .right-full, and .top-full utility classes. More information: uswds#5633

2022-06-08 N/A
  • Guidance
No

Updated demonstration of display:none. More information: uswds-site#1630