Layout

Components

Try layouts here

This page is utilizing the holy grail layout, but you can use the buttons below to toggle layouts and test them out by resizing the screen. Try the "Toggle container labels" button below to see the css classes on each of the containers inside .layout.

Important concepts

Thankfully, no one needs to be expert to use the .layout element. But it does help to understand a few important concepts before beginning.

Markup structure

The .layout class is designed to be placed on the <html> element itself, while the layout-body element is designed to be placed on the <body> element. All other elements are children of layout-body. Specific layouts are applied by adding a class with the format layout-{nameoflayout} to the html.layout element.

Nearly all layouts have the same eight elements, and the layout-body-hero element is always optional. While the layout, layout-body, layout-body-header, layout-body-footer, and layout-body-main elements are always required. The behavior of layout-body-menu and layout-body-aside depend on the layout.

The basic boilerplate for a layout is as follows:

					HTML
				

					<html class="layout layout-{nameoflayout}">
    <body class="layout-body">
        <header class="layout-body-header">Header</header>
        <section aria-label="hero" class="layout-body-hero">Hero</section>
        <nav class="layout-body-menu">Menu</nav>
        <main class="layout-body-main">Main</main>
        <aside class="layout-body-aside">Aside</aside>
        <footer class="layout-body-footer">Footer</footer>
    </body>
</html>
				

Apply your own spacing

The $layout-gap token is used to generate two separate classes that can be used to apply spacing to containers within each of the major layout areas. Spacing should not be applied to the layout-body-* containers themselves, but rather to elements within them - most often a single container that is a direct child of the layout-body-* element.

Class name	Use case	Examples of use case
`.layout-padding`	Layout areas that are not full width	The menu and aside areas. The main area when not in a single layout
`.layout-margin`	Full width layout areas	The header, footer, and hero. The main area when it is full width in a single layout.
`.layout-padding-tablet`	Same as `.layout-padding` but only applied on tablet breakpoint and above.
`.layout-margin-tablet`	Same as `.layout-margin` but only applied on tablet breakpoint and above.

Why not use gap? You certainly can apply any gap atomics to the layout-body to change spacing as you see fit. However, to provide adequate space to display focus rectangles and to ensure enough space to render dynamic inline elements (like heading anchors), spacing applied to an inner container is still the best choice.

Responsiveness

The layout components behavior is inextricably bound to Atlas's breakpoints. On narrow widths on all layouts, elements are stacked on top of one another. If you don't want an element to show on a particular screensize, you should either render nothing into it or hide the inner element.

Available layouts

There are five available layouts.

layout-single
layout-holy-grail
layout-sidecar-left
layout-sidecar-right
layout-twin

Layout Single

The layout-single class provides a simple stacked layout. It is equivalent to a series of marginless and paddingless stacked block level elements. All elements in a single layout should set their own margin somewhere within their nested containers. Most likely, you'll want to apply .layout-margin or some other container-like class to elements within the single layout. This is also the default layout that will render if no other class is provide.

How do I apply it? layout-single to the layout element.

Required elements: all except layout-body-hero.

Allowed elements: all.

Can have its height constrained? No.

Can have its menu collapsed? No.

Can have its aside collapsed? No.

					Text
				

					   Narrow
  ┌────────────┐
  │ Header     │
  ├────────────┤
  │ Hero       │
  ├────────────┤
  │ Menu       │
  ├────────────┤
  │ Main       │
  ├────────────┤
  │ Aside      │
  ├────────────┤
  │ Footer     │
  └────────────┘
				

The specification for this layout is as follows.

Screensize	Behavior
Narrow - Widescreen	All elements are stacked.

Holy Grail layout

Named after a layout that historically was difficult to implement the holy grail is stacked on narrow widths and progressively shows up to three columns as the screen widens.

How do I apply it? layout-holy-grail to the layout element.

Required elements: all except layout-body-hero.

Allowed elements: all.

Can have its height constrained? Yes, on desktop screens and wider. This differs from other constrainable layouts, because on tablet aside wraps under main, preventing us from constraining main's height effectively.

Can have its menu collapsed? Yes, on tablet screens and wider.

Can have its aside collapsed? Yes, on desktop screens and wider.

The following block is arranged from narrow widths on the left to wider widths on the right.

					Text
				

					   Narrow         Tablet           Desktop
  ┌────────────┐ ┌──────────────┐ ┌──────────────────────┐
  │ Header     │ │Header        │ │ Header               │
  ├────────────┤ ├──────────────┤ ├──────────────────────┤
  │ Hero       │ │Hero          │ │ Hero                 │
  ├────────────┤ ├─────┬────────┤ ├─────┬────────┬───────┤
  │ Menu       │ │Menu │ Main   │ │Menu │ Main   │ Aside │
  ├────────────┤ │     │        │ │     │        │       │
  │ Main       │ │     │        │ │     │        │       │
  ├────────────┤ │     ├────────┤ │     │        │       │
  │ Aside      │ │     │ Aside  │ │     │        │       │
  ├────────────┤ ├─────┴────────┤ ├─────┴────────┴───────┤
  │ Footer     │ │Footer        │ │ Footer               │
  └────────────┘ └──────────────┘ └──────────────────────┘
				

The specification for this layout is as follows.

Screensize	Behavior
Narrow	All elements are stacked.
Tablet	Menu and main are side by side. Main is wider than menu. Aside has a collapsed height and is tucked under main.
Desktop	Menu, main, aside are side by side. Main is wider than menu.

Sidecar left layout

A "sidecar" is a smaller companion container that sits beside the main content container on tablet screens and wider. In layout-sidecar-left the sidecar refers to the layout-body-menu element, which sits to the left of layout-body-main. Unlike other layouts, this layout does not allow the usage of the layout-body-aside containers.

How do I apply it? layout-sidecar-left to the layout element.

Required elements: all except layout-body-hero and layout-body-aside (see allowed elements).

Allowed elements: all except layout-body-aside.

Can have its height constrained? Yes, on tablet screens and wider.

Can have its menu collapsed? Yes, on tablet screens and wider.

Can have its aside collapsed? No (aside is not present).

The following block is arranged from narrow widths on the left to wider widths on the right.

					txt
				

					   Narrow           Tablet and wider
  ┌────────────┐   ┌──────────────┐
  │ Header     │   │Header        │
  ├────────────┤   ├──────────────┤
  │ Hero       │   │Hero          │
  ├────────────┤   ├─────┬────────┤
  │ Menu       │   │Menu │ Main   │
  ├────────────┤   │     │        │
  │ Main       │   │     │        │
  │            │   │     │        │
  │            │   │     │        │
  ├────────────┤   ├─────┴────────┤
  │ Footer     │   │Footer        │
  └────────────┘   └──────────────┘
				

The specification for this layout is as follows.

Screensize	Behavior
Narrow	All elements are stacked.
Tablet and wider	Menu and main are side by side. Main is wider than menu.

Sidecar right layout

The "sidecar" remains as defined in the section above, but in layout-sidecar-right the sidecar refers to the layout-body-aside element, which sits to the right of layout-body-main on tablet screens and wider. Unlike other layouts, this layout does not allow the usage of the layout-body-menu containers.

How do I apply it? layout-sidecar-right to the layout element.

Required elements: all except layout-body-hero and layout-body-menu (see allowed elements).

Allowed elements: all except layout-body-menu.

Can have its height constrained? Yes, on tablet screens and wider.

Can have its menu collapsed? No.

Can have its aside collapsed? Yes, on tablet screens and wider.

The following block is arranged from narrow widths on the left to wider widths on the right.

					txt
				

					  Narrow           Tablet and wider
 ┌──────────────┐ ┌──────────────────────┐
 │Header        │ │ Header               │
 ├──────────────┤ ├──────────────────────┤
 │Hero          │ │ Hero                 │
 ├──────────────┤ ├───────────────┬──────┤
 │Main          │ │ Main          │ Aside│
 │              │ │               │      │
 │              │ │               │      │
 ├──────────────┤ │               │      │
 │Aside         │ │               │      │
 ├──────────────┤ ├───────────────┴──────┤
 │Footer        │ │ Footer               │
 └──────────────┘ └──────────────────────┘
				

The specification for this layout is as follows.

Screensize	Behavior
Narrow	All elements are stacked.
Tablet and wider	Main and aside are side by side. Main is wider than aside.

Twin layout

On tablet screens and large the twin layout allows two containers (main and aside) to share the central part of the screen. Unlike some of the other containers these two containers continue to grow beyond the boundaries of the widescreen breakpoint. This means the text-based content rendered in either should consider setting a maximum width to ensure readability. This layout is ideal for a side-by-side experience, where a user might read an article in main and perform some interactive task, such as editing code, in aside.

How do I apply it? layout-twin to the layout element.

Required elements: all except layout-body-hero and layout-body-menu (see allowed elements).

Allowed elements: all except layout-body-menu.

Can have its height constrained? Yes, on tablet screens and wider.

Can have its aside collapsed? Yes, on tablet screens and wider.

The following block is arranged from narrow widths on the left to wider widths on the right.

					txt
				

					  Narrow           Tablet and wider
 ┌──────────────┐ ┌──────────────────────┐
 │Header        │ │ Header               │
 ├──────────────┤ ├──────────────────────┤
 │Hero          │ │ Hero                 │
 ├──────────────┤ ├───────────┬──────────┤
 │Main          │ │ Main      │     Aside│
 │              │ │           │          │
 │              │ │           │          │
 ├──────────────┤ │           │          │
 │Aside         │ │           │          │
 ├──────────────┤ ├───────────┴───-──────┤
 │Footer        │ │ Footer               │
 └──────────────┘ └──────────────────────┘
				

The specification for this layout is as follows.

Screensize	Behavior
Narrow	All elements are stacked.
Tablet and wider	Main and aside are side by side. Main and aside are the same width

Layouts with individually scrolling content containers

If you'd like central containers to scroll individually, instead of the page itself, you have to constrain the height of the layout to the viewport. In order to do that, you can add the .layout-constrained class to the html.layout element. This has no effect on narrow screens or on the single layout, but will work on most other layouts on tablet and larger (the exception being holy grail, which kicks in on desktop widths). See each layout's individual section for behavior specific to it.

This requires the use of some very lightweight client JavaScript to updates a few values on the HTML element as the screen resizes. This means you must install @microsoft/atlas-js and import and call the initLayout in your client scripts for this behavior to work. See how this site does it on GitHub.

How does constraint work?

When constraint is active the height of the page is calculated to be 100vh (i.e. the size of the viewport) plus the size of the hero. This means:

Main (and any container horizontally adjacent to it) will have a height equal to the viewport height minus the footer's height and the header's height.
Developers must still consider narrow views first. This behavior does not change scroll on narrow screens or mobile devices.
Consider also whether to omit footer or move footer into a different container for a more perfect full-screen fit.

Why is hero excluded from height calculation?

The hero is full width and never side by side with another container. It needn't be scrolled individually and what's more doing so would be quite an odd behavior.
Including it will not harm the experience, but it isn't recommended when using height constraints.
Users will have to scroll past hero to get to the content containers. If you do include it, ensure it isn't too tall.
Remember, the hero is always optional.

A flyout is a container that appears on the side of the screen. It provides additional space to render elements that you may not always want to be visible. Atlas's optional flyout container can be added to any layout. This container has several important characteristics:

It is not available on narrow and tablet-size screens. There simply isn't room for it. This means that whatever content is available in this sidebar, should be rendered elsewhere on narrow/tablet screen sizes. Typically, this would be done in a modal that renders "on top" of the other containers. Atlas does not implement this for you.
The flyout can be shown/hidden by adding/removing the .layout-flyout-active class to the .layout element.
The default width of the flyout on desktop can be customized with the --layout-flyout-width-desktop CSS variable.
This means developers must handle mobile and tablet widths with a different solution, such using a modal on narrow screens.
On expand/collapse of the flyout, it's recommended developers perform manual focus handling to ensure that focus is not lost for screenreaders.
The same should happen on resize.

In certain scenarios, it may be advantageous to collapse the left-hand menu element on layouts that have this container. To do this, add .layout-menu-collapsed to the html element of your page. This will hide the menu element and rearrange containers on layouts that support it, such as layout-holy-grail and layout-sidecar-left.

Collapsing the right-hand aside

Similarly, the right-hand aside can be collapsed by adding .layout-aside-collapsed to the html element. This narrows the aside to a minimal width on layouts that support it: layout-holy-grail, layout-sidecar-right, and layout-twin.

Scaling container widths

On wider screens, the menu and aside containers automatically scale up to give navigation and supplementary content more room. This happens at two breakpoints:

Screen width	Sidebar width
Below `1500px`	`275px` (default)
`1500px` and above	`320px`
`2000px` and above	`450px`

When the flyout is active, sidebar widths step down one notch to make room for the flyout column. If the sidebars are already at the default 275px, no further reduction occurs.

Screen width	Sidebar width (flyout active)
Below `1500px`	`275px` (unchanged)
`1500px` and above	`275px` (stepped down from `320px`)
`2000px` and above	`320px` (stepped down from `450px`)
`2500px` and above	`450px` (no reduction)

This scaling is built in and requires no additional classes or configuration. The values can still be overridden with the --layout-menu-expanded-target-width and --layout-aside-expanded-target-width CSS variables described in Customizing layout dimensions with CSS variables.

Accessibility Concerns

ARIA landmarks

Due to the recommendation that all content be rendering into ARIA landmark regions, the hero element should be a <section> element with an unique aria-label (or aria-labelled by).

DOM order should reflect visual hierarchy

Grid areas, the CSS feature powering the layout component, have the potential to make DOM order different from visual hierarchy (i.e. which element seems like it is first on the page). This can cause confusion for keyboard users who use tab to navigate through web pages. The recommended order of elements within layout-body is as follows:

Header
Hero (if present)
Menu (if present)
Main
Aside (if present)
Footer

See WCAG on Making the DOM order match the visual order for more information on this topic.

Customizing layout dimensions with CSS variables

The layout component exposes several CSS custom properties that let you tune column widths and spacing without writing new grid definitions. Override these variables on the .layout element (or any ancestor) to customize dimensions site-wide, or scope them to a specific page.

Variable	Default	Description
`--layout-menu-expanded-target-width`	`275px`	The width of the menu column when expanded.
`--layout-menu-collapsed-width`	`68px`	The width of the menu column when collapsed via `.layout-menu-collapsed`.
`--layout-aside-expanded-target-width`	`275px`	The width of the aside column when expanded.
`--layout-aside-collapsed-width`	`68px`	The width of the aside column when collapsed via `.layout-aside-collapsed`.

For example, to make the menu wider on a particular page:

					css
				
					.layout {
    --layout-menu-expanded-target-width: 350px;
}

Or to make the aside narrower:

					css
				
					.layout {
    --layout-aside-expanded-target-width: 200px;
}

Variable	Default	Description
`--layout-flyout-width-desktop`	`320px`	The width of the flyout container on desktop screens.

					css
				
					.layout {
    --layout-flyout-width-desktop: 400px;
}

Layout gap

Variable	Default	Description
`--layout-gap`	`16px` (narrow), `24px` (desktop)	The inline padding applied by `.layout-padding` and consumed by full-width elements like hero and site header.

These variables are consumed by the grid definitions internally — you do not need to redefine any grid templates. Simply set the variable and the layout will adapt.

Advanced topic - switching layouts on the fly

Because layouts generally contain the same elements and because the current layout is determined by a singular class on the .layout element, changing layout is as easy as swapping out a class.

					JavaScript
				
					document.documentElement.classList.remove('layout-single');
document.documentElement.classList.add('layout-holy-grail');

You'll seldom have occasion to do this in the middle of a user's visit, but it can be useful for things like opening a code editor in a wider layout or adopting a focused reading mode.

Layout

Try layouts here

Important concepts

Markup structure

Apply your own spacing

Responsiveness

Available layouts

Layout Single

Holy Grail layout

Sidecar left layout

Sidecar right layout

Twin layout

Layouts with individually scrolling content containers

How does constraint work?

Why is hero excluded from height calculation?

An optional flyout container

Collapsing the left-hand menu

Collapsing the right-hand aside

Scaling container widths

Accessibility Concerns

ARIA landmarks

DOM order should reflect visual hierarchy

Customizing layout dimensions with CSS variables

Menu and aside widths

Flyout width

Layout gap

Advanced topic - switching layouts on the fly