Migration guide
How to migrate to navigation system from the old Atlassian navigation, side navigation, and page layout packages.Neutral selected states
When the platform-dst-tokens-finesse feature flag is enabled, this component uses the new neutral treatment for selected states.
Further guidance for Atlassians
This page covers the Design System visual primitives. For guidance on the broader platform components — such as the customisation modal, app switcher data, and user personalisation — see navigation resources (Atlassians only).
This guide covers migration from the old page layout, Atlassian navigation, and side navigation to the new navigation system and side nav items, (opens new window).
Page layout
Slots
| Old | New |
|---|---|
PageLayout | Root |
Banner | Banner |
TopNavigation | TopNav |
LeftSidebar, LeftSidebarWithoutResize | SideNav |
LeftPanel | No equivalent. Use SideNav if it's navigation, or Panel if it's supplementary content. |
Content, Main | Main |
RightPanel | Panel |
RightSidebar | No equivalent. Use Panel, or a custom two-column layout inside Main. |
Hooks
| Old | New |
|---|---|
useCustomSkipLink | useSkipLink — see custom skip links |
useLeftSidebarFlyoutLock | No equivalent. Use useExpandSideNav() to force the side nav open. |
usePageLayoutResize | No equivalent. Use useExpandSideNav() to expand the side nav, or the onExpand and onCollapse callbacks on <SideNav> to track its state. |
useGlobalTheme | No equivalent. Theme is applied automatically. |
Constants
The legacy CSS variables are unsafe and encourage rigidity in the layout system. They should be removed:
LEFT_SIDEBAR_WIDTHRIGHT_SIDEBAR_WIDTHLEFT_PANEL_WIDTHRIGHT_PANEL_WIDTHBANNER_HEIGHTTOP_NAVIGATION_HEIGHT
These will be temporarily available from the
@atlaskit/navigation-system/legacy/css-variables entrypoint.Top nav is for global, cross-app actions only. Items such as the app switcher, search, create, help, notifications, settings, and profile are consistent across every Atlassian product.
Layout
AtlassianNavigation is replaced by TopNav.
The old render props (renderProductHome, renderAppSwitcher, renderCreate, etc.) are replaced
by three layout slots:
TopNavStart— place the side nav toggle button, app logo, and app switcher hereTopNavMiddle— place search and create hereTopNavEnd— place help, notifications, settings, profile, and sign in here
HORIZONTAL_GLOBAL_NAV_HEIGHT has no equivalent. Any usage should be refactored out, or hardcoded
if necessary.
PrimaryButton and PrimaryDropdownButton have no equivalent. Primary nav links are app-specific
and belong in the side nav. The product
home and app switcher, previously also in this area, now live in TopNavStart.
useOverflowStatus was used to manage overflow of primary items and is no longer applicable.
| Old | New |
|---|---|
AppHome, CustomProductHome, ProductHome | AppLogo or CustomLogo inside <TopNavStart> |
AppSwitcher, AppSwitcherNav4 | AppSwitcher inside <TopNavStart> |
Secondary items
| Old | New |
|---|---|
Search | Search inside <TopNavMiddle> |
Create | CreateButton inside <TopNavMiddle> |
Help | Help inside <TopNavEnd> |
Notifications | Notifications inside <TopNavEnd> |
Settings | Settings inside <TopNavEnd> |
Profile | Profile inside <TopNavEnd> |
IconButton | EndItem inside <TopNavEnd> |
SignIn | LogIn inside <TopNavEnd> |
Custom theming
Legacy custom theming is supported with a new API. See custom theming for details.
Loading states
The skeleton loading components (NavigationSkeleton, SkeletonCreateButton, SkeletonIconButton,
SkeletonPrimaryButton, SkeletonSwitcherButton) have no equivalent in the new navigation system.
Side nav is for app-specific navigation — use it to navigate within an app, between sections, projects, boards, spaces, and so on. The side nav is resizable, collapsible, and supports user customisation of menu items.
Side nav items are in the separate side nav items, (opens new window) package.
Layout
| Old | New |
|---|---|
SideNavigation | SideNav |
NavigationContent | SideNavBody |
NavigationHeader | SideNavHeader |
Header | No equivalent. There is no opinionated presentation component for the header slot — build your own content inside SideNavHeader. |
NavigationFooter | SideNavFooter |
Footer | No equivalent. There is no opinionated presentation component for the footer slot — build your own content inside SideNavFooter. |
Sections and items
| Old | New |
|---|---|
LinkItem | LinkMenuItem |
ButtonItem | ButtonMenuItem |
CustomItem | No equivalent. Use ButtonMenuItem or LinkMenuItem with custom content. |
Section | MenuSection |
HeadingItem | MenuSectionHeading |
SkeletonItem, SkeletonHeadingItem, LoadingItems | See loading states |
Nesting
The nested navigation pattern (NestingItem, NestableNavigationContent) has been replaced with
expandable menu items, (opens new window).
GoBackItem and useShouldNestedElementRender have no equivalent.