--- title: Migration guide description: How to migrate to navigation system from the old Atlassian navigation, side navigation, and page layout packages. order: 4 --- import SectionMessage from '@atlaskit/section-message'; import Link from '@atlaskit/link'; import { Code } from '@atlaskit/code'; 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](/components/page-layout), [Atlassian navigation](/components/atlassian-navigation), and [side navigation](/components/side-navigation) to the new navigation system and [side nav items](https://atlaskit.atlassian.com/packages/navigation/side-nav-items). ## 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_WIDTH - RIGHT_SIDEBAR_WIDTH - LEFT_PANEL_WIDTH - RIGHT_PANEL_WIDTH - BANNER_HEIGHT - TOP_NAVIGATION_HEIGHT These will be temporarily available from the @atlaskit/navigation-system/legacy/css-variables entrypoint. ## Atlassian navigation 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`](/components/navigation-system/layout/code#topnav). The old render props (`renderProductHome`, `renderAppSwitcher`, `renderCreate`, etc.) are replaced by three layout slots: - [`TopNavStart`](/components/navigation-system/layout/code#topnavstart) — place the side nav toggle button, app logo, and app switcher here - [`TopNavMiddle`](/components/navigation-system/layout/code#topnavmiddle) — place search and create here - [`TopNavEnd`](/components/navigation-system/layout/code#topnavend) — 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. ### Primary items `PrimaryButton` and `PrimaryDropdownButton` have no equivalent. Primary nav links are app-specific and belong in the [side nav](/components/navigation-system/layout/examples#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](/components/navigation-system/layout/custom-theming) for details. ### Loading states The skeleton loading components (`NavigationSkeleton`, `SkeletonCreateButton`, `SkeletonIconButton`, `SkeletonPrimaryButton`, `SkeletonSwitcherButton`) have no equivalent in the new navigation system. ## Side navigation 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](https://atlaskit.atlassian.com/packages/navigation/side-nav-items) 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](https://atlaskit.atlassian.com/packages/navigation/side-nav-items#expandable-menu-item). `GoBackItem` and `useShouldNestedElementRender` have no equivalent. --- ## Related - [Layout](/components/navigation-system/layout) - [Top nav items](/components/navigation-system/top-nav-items) - [Side nav items](https://atlaskit.atlassian.com/packages/navigation/side-nav-items)