Use our flexible grid system to structure website content. The grid is mobile-first, powered by flexbox, and based on a 12-column system.
How it works
The grid system uses a series of containers, rows, and columns to lay out and align content. The following row and corresponding code are an example of and in-depth look at how the grid comes together.
This example code creates three equal-width columns on tablet, desktop, and widescreen devices by using our predefined grid classes. Those columns are centered in the page with the parent
The following sections break the layout grid down and describe how it works.
Containers, rows, and columns
grid-containercenters the container and gives it a maximum width of
desktop(1024px). If you would like the grid to span the full width of the page, do not use
grid-containercan also accept any breakpoint width, like
widescreen. Set the default max width with
$theme-grid-container-max-widthin your USWDS settings configuration using unit tokens.
- By default,
padding-xof 2 units at narrow widths, and a padding-x of 4 units at
desktopand wider. Control these values by customizing
$theme-site-margins-breakpointin your USWDS settings configuration using unit tokens.
- Rows: Columns must have a
grid-rowas a parent.
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, use
grid-col-4for each item.
- Equal-width columns: With flexbox, grid columns without a specified width will display as equal-width columns. For example, four instances of
grid-colwill display as one-quarter-width columns across all sizes. Refer to the auto-layout columns section for more examples.
- Gutters: Rows and columns don’t have any gutters by default, but gutters can be added by including
grid-gap-lgat the row level. Refer to 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-4applies to tablet, desktop, and widescreen devices but not at
mobile-lgor any width below the tablet breakpoint). Refer to responsive variants for a full list.
- Sass mixins: You can use predefined grid classes (like
grid-col-4) for presentational markup or Sass mixins for more semantic markup.
Auto layout columns
.grid-col-auto items fit the natural width of their content.
.grid-col-fill items flex to fill the available space as illustrated in the following example row and code.
Same at all breakpoints
For columns that should maintain the same proportion at any viewport width, use the
.grid-col-* classes. Specify a numbered class when you need a column of a specific width; otherwise, use
.grid-col-[1-12] sets a fixed width of [n] grid columns in a 12-column grid.
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:) as illustrated in the following rows and corresponding code.
Mix and match
Don’t want your columns to simply stack in some breakpoints? Use a combination of different classes for each breakpoint as needed. See the following example rows and corresponding code for a better idea of how it all works.
.grid-offset-[1-12] offsets an item by the specified number of grid columns as shown in the following example.
Items wrap when the sum of the grid columns is more than 12 as shown in the following example.
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 as shown in the following example.
grid-gap-lg adds a larger gap (or gutter) between each column in a row than `grid-gap`. 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
The following example row and code illustrate large gutters.
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 and maps determine the number of columns, gutter width, and media-query point at which to begin floating columns. We use variables to generate the predefined grid classes documented on this page, as well as for the custom mixins noted under Spacing settings and Utilities settings.
Mixins can be used in conjunction with grid variables to add grid functionality to semantic component Sass.
You can modify the variables to your 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.
Meaningful code and guidance updates are listed in the following table:
Updated value of
Updated value of