Utilities
Display
Control the position and display characteristics of an item
CSS properties
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>
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.
.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
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
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.
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.
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.
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>
The pin utilities position an item absolutely to the specified side.
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 (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 |
|---|---|
| $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 | Description |
|---|---|---|---|
| 2023-12-08 | 3.7.1 |
|
Fixed a bug that prevented the CSS from generating |
| 2022-06-08 | N/A |
|
Updated demonstration of |
