Utilities
Layout grid
Use our flexible grid system to structure website content. The grid is mobile-first, powered by flexbox, and based on a twelve-column system.
How it works
The grid system uses a series of containers, rows, and columns to lay out and align content. Below is an example and an in-depth look at how the grid comes together.
<div class="grid-container">
<div class="grid-row">
<div class="tablet:grid-col">tablet:grid-col</div>
<div class="tablet:grid-col">tablet:grid-col</div>
<div class="tablet:grid-col">tablet:grid-col</div>
</div>
</div>
The above example creates three equal-width columns on tablet, desktop, and widescreen devices using our predefined grid classes. Those columns are centered in the page with the parent grid-container
container.
Breaking it down, here’s how it works:
Containers, rows, and columns
- Containers:
grid-container
centers the container and gives it a maximum width ofdesktop
(1024px). If you would like the grid to span the full width of the page, do not usegrid-container
.grid-container
can also accept any breakpoint width likegrid-container-tablet-lg
orgrid-container-widescreen
. Set the default max width with$theme-site-max-width
inuswds-theme-spacing.scss
.- By default,
grid-container
s have padding-x of 2 units, with a padding-x of 4 units atdesktop
and wider. Control these values with the values of$theme-site-margins-mobile-width
,$theme-site-margins-width
and$theme-site-margins-beakpoint
inuswds-theme-spacing.scss
.
- Rows: Columns must have a
grid-row
as a parent. - Columns:
grid-col-[1-12]
indicates the number of columns the item spans out of a possible 12 per row. So, if you want three equal-width columns across, usegrid-col-4
for each item.
Additional functionality
- Equal-width columns: With flexbox, grid columns without a specified width will display as equal-width columns. For example, four instances of
grid-col
will display as one-quarter-width columns across all sizes. See the auto-layout columns section for more examples. - Gutters: Rows and columns don’t have any gutters by default, but they can be added by adding
grid-gap-sm
,grid-gap
, orgrid-gap-lg
at the row level. See gutters for more info. - Media queries: Grid breakpoints are based on minimum width media queries, meaning they apply to that specific width and all greater widths (e.g.,
tablet:col-4
applies to tablet, desktop, and widescreen devices, but not atmobile-lg
or any width below the tablet breakpoint). See responsive variants for full list. - Sass mixins: You can use predefined grid classes (like
grid-col-4
) for presentational markup or Sass mixins for more semantic markup.
Responsive variants
Width | Size | Utility class | Columns | Gutters | Nestable |
---|---|---|---|---|---|
Smallest | ≥0 | .grid-col | 12 | 0 | Yes |
Mobile large | ≥480px | .mobile-lg:grid-col | 12 | 0 | Yes |
Tablet | ≥640px | .tablet:grid-col | 12 | 0 | Yes |
Desktop | ≥1024px | .desktop:grid-col | 12 | 0 | Yes |
Auto layout columns
Variable width content
.grid-col-auto
items fit the natural width of their content.
.grid-col
and .grid-col-fill
items flex to fill the available space.
<div class="grid-container">
<div class="grid-row">
<div class="grid-col-auto">.grid-col-auto</div>
<div class="grid-col-fill">.grid-col</div>
<div class="grid-col-fill">.grid-col</div>
<div class="grid-col-auto">.grid-col-auto</div>
</div>
</div>
Responsive classes
Same at all breakpoints
For columns that should maintain the same proportion at any viewport width, use the .grid-col
and .grid-col-*
classes. Specify a numbered class when you need a column of a specific width; otherwise, use .grid-col
.
.grid-col-[1-12]
set a fixed width of [n] grid-columns in a 12-column grid.
<div class="grid-row">
<div class="grid-col-1">.grid-col-1</div>
<div class="grid-col-2">.grid-col-2</div>
<div class="grid-col-3">.grid-col-3</div>
<div class="grid-col-4">.grid-col-4</div>
<div class="grid-col-2">.grid-col-2</div>
</div>
<div class="grid-row">
<div class="grid-col-8">.grid-col-8</div>
<div class="grid-col-2">.grid-col-2</div>
<div class="grid-col-2">.grid-col-2</div>
</div>
Stacked columns at narrow widths
Columns are full-width until the narrowest breakpoint specified in a .grid-col
class. For instance, using a single set of tablet:grid-col-*
classes, you can create a basic grid system that starts out stacked before displaying as columns at the tablet breakpoint (tablet:
).
<div class="grid-row">
<div class="tablet:grid-col">.tablet:grid-col</div>
<div class="tablet:grid-col">.tablet:grid-col</div>
<div class="tablet:grid-col">.tablet:grid-col</div>
</div>
<div class="grid-row">
<div class="tablet:grid-col-4">.tablet:grid-col-4</div>
<div class="tablet:grid-col-8">.tablet:grid-col-8</div>
</div>
Mix and match
Don’t want your columns to simply stack in some breakpoints? Use a combination of different classes for each breakpoints as needed. See the example below for a better idea of how it all works.
<!-- Stack the columns on mobile by making one full-width and the other half-width -->
<div class="grid-row">
<div class="tablet:grid-col-8">.tablet:grid-col-8</div>
<div class="grid-col-6 tablet:grid-col-4">.col-6 .tablet:grid-col-4</div>
</div>
<!-- Columns start at 50% wide on mobile and bump up to 33.3% wide on desktop -->
<div class="grid-row">
<div class="grid-col-6 tablet:grid-col-4">.col-6 .tablet:grid-col-4</div>
<div class="grid-col-6 tablet:grid-col-4">.col-6 .tablet:grid-col-4</div>
<div class="grid-col-6 tablet:grid-col-4">.col-6 .tablet:grid-col-4</div>
</div>
<!-- Columns are always 50% wide, on mobile and desktop -->
<div class="grid-row">
<div class="grid-col-6">.col-6</div>
<div class="grid-col-6">.col-6</div>
</div>
Offsetting columns
.grid-offset-[1-12]
offsets the item by the specified number of grid columns.
<div class="grid-row">
<div class="grid-col-8 grid-offset-4">.grid-col-8.grid-offset-4</div>
</div>
Column wrapping
Items wrap when the sum of the grid columns is more than 12.
<div class="grid-row">
<div class="grid-col-8">.grid-col-8</div>
<div class="grid-col-3">.grid-col-3</div>
<div class="grid-col-5">.grid-col-5</div>
</div>
Gutters
Default gutter
Add grid-gap
to a grid row to add a gap (or gutter) between each column in the row. The default gap width is 2 units and 4 units at desktop
and higher. Customize the width of the gap by adjusting the value of $theme-column-gap
in project settings.
<div class="grid-row grid-gap">
<div class="grid-col-4">
<div>.grid-col-4</div>
</div>
<div class="grid-col-4">
<div>.grid-col-4</div>
</div>
<div class="grid-col-4">
<div>.grid-col-4</div>
</div>
</div>
Large gutter
grid-gap-lg
adds a larger gap (or gutter) between each column in a row. The default large gap width is 32px (4 spacing units). Customize the width of the large gap by adjusting the value of $theme-column-gap-lg
in project settings. There is also a .grid-gap-sm
(2px) set with $theme-column-gap-sm
. Also, you can add the following system values with grid-gap
:
grid-gap-2px
grid-gap-05
grid-gap-1
grid-gap-2
grid-gap-3
grid-gap-4
grid-gap-5
grid-gap-6
<div class="grid-row grid-gap-lg">
<div class="grid-col-4">
<div>.grid-col-4</div>
</div>
<div class="grid-col-4">
<div>.grid-col-4</div>
</div>
<div class="grid-col-4">
<div>.grid-col-4</div>
</div>
</div>
Sass mixins
When generating your CSS from USWDS source files, you have the option of customizing many system defaults by modifying project theme variables. USWDS also provides grid mixins for adding grid functionality to custom semantic component CSS.
Variables
Variables and maps determine the number of columns, the gutter width, and the media query point at which to begin floating columns. We use these to generate the predefined grid classes documented above, as well as for the custom mixins listed below.
uswds-theme-spacing.scss
// Values are set as units tokens.
$theme-column-gap-sm: 2px;
$theme-column-gap-md: 2;
$theme-column-gap-lg: 3;
$theme-column-gap-mobile: 2;
$theme-column-gap-desktop: 4;
$theme-grid-container-max-width: 'desktop';
$theme-site-max-width: 'desktop';
$theme-site-margins-breakpoint: 'desktop';
$theme-site-margins-width: 4;
$theme-site-margins-mobile-width: 2;
uswds-theme-utilities.scss
// Turn on or off breakpoints
$theme-utility-breakpoints: (
'card': false, // 160px
'card-lg': false, // 240px
'mobile': false, // 320px
'mobile-lg': true, // 480px
'tablet': true, // 640px
'tablet-lg': false, // 800px
'desktop': true, // 1040px
'desktop-lg': false, // 1200px
'widescreen': false, // 1400px
);
Mixins
Mixins can be used in conjunction with the grid variables to add grid functionality to semantic component Sass.
// Creates a wrapper for a series of rows
// $container-size can be mobile, mobile-lg, tablet, tablet-lg, desktop, desktop-lg, or widescreen
@include grid-container;
@include grid-container($container-size);
// Creates a wrapper for a series of columns
@include grid-row;
// Specify the width between columns
// $gap-size can be sm, md, lg, 2px, 05, 1, 3, 4, 6
@include grid-gap;
@include grid-gap($gap-size);
// Make the element full-width
@include u-width(full);
// Specify the number of columns the element should span
// $columns can be auto, fill, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
@include grid-col;
@include grid-col($columns);
// Get fancy by offsetting or changing the display order
// $offset can be none, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
@include grid-offset($offset);
// $order can be first, last, initial, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
@include u-order($order);
Example usage
You can modify the variables to your own custom values, or just use the mixins with their default values. Here’s an example of using the default settings to create a two-column layout with a gap between.
.example-container {
@include grid-container;
}
.example-row {
@include grid-row;
// Add column gaps
&.content-row {
@include grid-gap;
}
}
.example-content-main {
@include u-width(full);
@include at-media(tablet) {
@include grid-col(6);
}
@include at-media(desktop) {
@include grid-col(8);
}
}
.example-content-secondary {
@include u-width(full);
@include at-media(tablet) {
@include grid-col(6);
}
@include at-media(desktop) {
@include grid-col(4);
}
}