---
title: Layout
description: Layout components define a page’s structure and the areas for navigation and content.
order: 1
---

import SectionMessage from '@atlaskit/section-message';

import { CustomSkipLinkExample } from '../../examples/constellation/layout/custom-skip-links';
import { ExpandSideNavButtonExample } from '../../examples/constellation/layout/expand-side-nav';
import { ToggleSideNavKeyboardShortcutExample } from '../../examples/constellation/layout/toggle-side-nav-keyboard-shortcut';

import { PageLayoutDiagram } from './diagram';

The full page layout with all areas rendered has the structure depicted below, or see the
[interactive example (Atlassians only)](https://go.atlassian.com/nav4-interactive-example).

<PageLayoutDiagram />

When composing your page layout ensure that:

- The `Root` element wraps your entire view
- All layout areas are rendered as immediate children of the `Root` element

## Layout areas

These are the distinct areas in the layout. These components are designed to contain other
components and content.

For examples see
[ready-made navigation experiences (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE).

### Banner

Use the `Banner` area to render a [banner](/components/banner) component. It will always display at
the top of the screen.

### Top nav

Use the `TopNav` to render [top nav items](/components/navigation-system/top-nav-items).

- It will display at the top of the screen, below the banner if one is present. It has a fixed
  height of 48px.
- Use the [top nav slots](#top-nav-slots) to position actions within top nav.
- The top nav is [responsive](/components/navigation-system/top-nav-items/examples#responsive), with
  the top nav items changing according to the viewport size.

#### Top nav slots

The TopNav has three layout components that you must use to position
[top nav items](/components/navigation-system/top-nav-items) within the top nav flexbox.

- `TopNavStart`. Area for left-aligned items.
- `TopNavMiddle`. Area for centre-aligned items.
- `TopNavEnd`. Area for right-aligned items.

#### Top nav custom theming

See the [custom theming](/components/navigation-system/layout/custom-theming) tab.

### Side nav

- Use the `SideNav` to render [side nav items](/components/navigation-system/side-nav-items). It
  will show on the left of the screen. The default width of the side nav is 320px.
- Use the [side nav slots](#side-nav-slots) to position content within the side nav.
- The side nav is collapsable and expandable, resizable, responsive, and offers flyout behaviour.

#### Side nav slots

The `SideNav` has three layout components that you can use to position components within the side
nav flexbox.

- `SideNavHeader`. The top part of the side nav.
- `SideNavContent`. The middle part of the side nav. It acts as a scroll container. It will grow to
  take up the available space — this is used to push the footer to the bottom of the side nav.
- `SideNavFooter`. The bottom part of the side nav.

Note: make sure to render `SideNavContent` to ensure that the footer is positioned at the bottom of
the side nav, simulating a sticky footer.

#### Side nav collapse/expand

The side nav can be collapsed and expanded using the the `SideNavToggleButton` from
[top nav items](/components/navigation-system/top-nav-items/examples#start-items).

There are two hooks available for programmatically toggling the side nav.

- `useExpandSideNav`
- `useToggleSideNav`

<SectionMessage title="Usage">
	These hooks need to be used by components that are rendered as a child of <a href="#root">Root</a>
	, as they require the internal React context that it provides.
</SectionMessage>

##### useExpandSideNav

Returns a function that will expand the side nav.

This can be useful for ensuring the side nav is expanded before displaying an onboarding spotlight,
for example. If the side nav is already expanded, it will simply no-op.

<Example Component={ExpandSideNavButtonExample} appearance="source-only" />

##### useToggleSideNav

Returns a function that will toggle the side nav.

This is useful for toggling the side nav based on a keyboard shortcut.

<Example Component={ToggleSideNavKeyboardShortcutExample} appearance="source-only" />

#### Side nav flyout

- In the collapsed state, hovering over the `SideNavToggleButton` from
  [top nav items](/components/navigation-system/top-nav-items/examples#start-items) will trigger the
  side nav to open as an overlay. Moving the curser away will close it. If there are any open
  supported ADS layering components (e.g. Popups, Dropdown menus) within the side nav, the flyout
  will stay locked open, until the layering components are closed.

- The expansion and collapse of the side nav flyout is animated on **supported browsers**.
  Currently, Firefox does not support the animation. Instead, it will instantly expand and collapse.

See the [interactive example (Atlassians only)](https://go.atlassian.com/nav4-interactive-example).

#### Side nav resizing

- You can optionally render a [side nav panel splitter](#resizable-areas) as a child to make the
  side nav resizable. It is resized using the drag handle. When hovering on the drag handle the
  mouse pointer changes to a resize pointer.
- The side nav can be resized to a minimum width of 240px, and a maximum width equal to 50% of the
  total viewport width. It retains this resized width even after collapsing, reopening, or
  refreshing the page. When resizing, any open layer components (e.g. popups, dropdowns, selects,
  tooltips) will be closed.
- The side nav panel splitter can be also double clicked to collapse the side nav.

See the [interactive example (Atlassians only)](https://go.atlassian.com/nav4-interactive-example).

#### Side nav responsive

- At `s`, `xs`, and `xxs` breakpoints (i.e. viewports smaller than 1024px), the side nav
  automatically collapses to make room for the content. Users have the option to manually
  [open or close the side nav](/components/navigation-system/layout/examples#side-nav-collapseexpand)
  according to their preferences. Doing so will open it as an overlay.
- At `xs` and `xxs` breakpoints (i.e. viewports smaller than 768px), the max width of the overlay
  side nav is either 320px or 90% of the screen width - whichever value is smaller.

See the [interactive example (Atlassians only)](https://go.atlassian.com/nav4-interactive-example).

### Main

Use `Main` for the [page header](/components/page-header) and main page content. It will expand to
fill available space.

- On large viewports `Main` can be fixed, meaning it will have its own scroll container and not use
  the body scroll.
- On small viewports, the element will always use body scroll, to make it easier to scroll the page
  when the content is tall.

### Aside

`Aside` is rendered to the right of the `Main` area.

- The default width of the Aside is 330px, and it is
  [resizable](/components/navigation-system/layout/examples#aside-resizing) and
  [responsive](/components/navigation-system/layout/examples#aside-responsive).
- On large viewports the Aside can be fixed, meaning it will have its own scroll container and not
  use the body scroll.
- On small viewports, the element will always use body scroll, to make it easier to scroll the page
  when the content is tall.

See the [interactive example (Atlassians only)](https://go.atlassian.com/nav4-interactive-example).

#### Aside resizing

You can optionally render a [panel splitter](#resizable-areas) as a child to make the `Aside`
resizable.

- It is resized using the drag handle. When hovering on the drag handle the mouse pointer changes to
  a resize pointer.
- The `Aside` can be resized to a minimum width of 120px, and a maximum width equal to 50% of the
  total viewport width. It retains this resized width even after refreshing the page.

See the [interactive example (Atlassians only)](https://go.atlassian.com/nav4-interactive-example).

#### Aside responsive

At `s`, `xs`, and `xxs` breakpoints (i.e. viewports smaller than 1024px), the `Aside` moves below
the `Main` area, and conforms to `Main` width and behaviour.

See the [interactive example (Atlassians only)](https://go.atlassian.com/nav4-interactive-example).

### Panel

The `Panel` is rendered to the right of the `Main` and `Aside` areas.

- The default width of the panel is 365px, which can be modified using the `defaultWidth` prop.
- The panel is
  [collapsable and expandable](/components/navigation-system/layout/examples#panel-collapseexpand),
  [resizable](/components/navigation-system/layout/examples#panel-resizing), and
  [responsive](/components/navigation-system/layout/examples#panel-responsive).

Common usage is to house
[Preview panel (Atlassians only)](https://atlaskit-website-staging.stg-east.frontend.public.atl-paas.net/#/packages/navigation/preview-panel)

#### Panel collapse/expand

The panel can be collapsed and expanded using a trigger of your choosing.

See the [interactive example (Atlassians only)](https://go.atlassian.com/nav4-interactive-example).

#### Panel resizing

You can optionally render a [panel splitter](#resizable-areas) as a child to make the panel
resizable. It can be resized using the drag handle. When hovering on the drag handle the mouse
pointer changes to a resize pointer.

- The panel can be resized larger than the `defaultWidth` to a maximum of 50% of content area
  (viewport minus `SideNav`).
- It retains this resized width even after collapsing, reopening, or refreshing the page.
- It has no ability to resize smaller than `defaultWidth`.

See the [interactive example (Atlassians only)](https://go.atlassian.com/nav4-interactive-example).

#### Panel responsive

At `m` breakpoints (between 1024-1440px), the `Panel` will overlay `Aside`. At `s` breakpoints and
below (less than 1024px) it will start to overlay the `Main` area.

See the [interactive example (Atlassians only)](https://go.atlassian.com/nav4-interactive-example).

## Resizable areas

Render a `PanelSplitter` in a layout area to make it resizable.

Resizing is supported for the following areas:

- [SideNav](/components/navigation-system/layout/examples#side-nav) - use `SideNavPanelSplitter`
- [Aside](/components/navigation-system/layout/examples#aside) - use `PanelSplitter`
- [Panel](/components/navigation-system/layout/examples#panel) - use `PanelSplitter`

See the [interactive example (Atlassians only)](https://go.atlassian.com/nav4-interactive-example).

| Area      | Default width      | Min width             | Max width                                    |
| --------- | ------------------ | --------------------- | -------------------------------------------- |
| `SideNav` | 320px              | 240px                 | 50% of viewport width                        |
| `Aside`   | 330px (modifiable) | 120px                 | 50% of viewport width                        |
| `Panel`   | 365px (modifiable) | Same as default width | 50% of content area (viewport minus SideNav) |

## Responsive

Layout areas respond to the viewport size. See default behaviour below, or the
[interactive example (Atlassians only)](https://go.atlassian.com/nav4-interactive-example).

| Breakpoint | Viewport      | Side nav                    | Aside        | Panel                                                       |
| ---------- | ------------- | --------------------------- | ------------ | ----------------------------------------------------------- |
| `xxs`      | 320 - 479px   | Collapsed; opens as overlay | Below Main   | Collapsed; opens as overlay (over Main)                     |
| `xs`       | 480 - 767px   | Collapsed; opens as overlay | Below Main   | Collapsed; opens as overlay (over Main)                     |
| `s`        | 768 - 1023px  | Collapsed; opens as overlay | Below Main   | Collapsed; opens as overlay (over Main)                     |
| `m`        | 1024 - 1439px | Expanded (inline)           | Next to Main | Collapsed; opens inline (or as overlay if Aside is present) |
| `l`        | 1440 - 1767px | Expanded (inline)           | Next to Main | Collapsed; Opens inline                                     |
| `xl`       | 1768+px       | Expanded (inline)           | Next to Main | Collapsed; Opens inline                                     |

## Custom skip links

Use `useSkipLink` to register custom skip links where appropriate. The `useSkipLink` hook accepts an
optional third argument to manually specify the index of the skip link in the list.

You can also optionally use the `useSkipLinkId` hook to retrieve a unique ID for use for your skip
link.

<Example Component={CustomSkipLinkExample} appearance="source-only" />
