DEV Community

HarmonyOS
HarmonyOS

Posted on

🚀 ArkTS Navigation: How to Build Modern Page Transitions in HarmonyOS

Read the original article：🚀 ArkTS Navigation: How to Build Modern Page Transitions in HarmonyOS

Introduction

Do you still use router for navigation in your HarmonyOS apps? You might be missing out on cleaner, more powerful transitions!
In this article, we’ll cover why Navigation is the new recommended approach for page navigation in ArkTS, how it works under the hood, and show a sample app where you can move from one page to another with modern stack management.

Why Not router Anymore?

router is simple but limited. It’s not designed for complex navigation scenarios (multi-level, stack, parameter passing, etc.) and lacks state management.
Navigationbrings stack-based navigation, easier back/forward transitions, and advanced UI customization.

Setting Up Navigation in ArkTS

You only need the built-in Navigation API, no extra library or third-party kit.
Below is a simple yet complete example of using Navigation between two pages:

Sample Code: Basic Stack Navigation

import { SecondPageBuilder } from "./SecondPage"

@Entry
@Component
struct Index {
  @Provide('NavPathStack') pageStack: NavPathStack = new NavPathStack()

  build() {
    Navigation(this.pageStack) {
      Column() {
        Button('Go SecondPage', { stateEffect: true, type: ButtonType.Capsule })
          .width('80%')
          .height(40)
          .margin(20)
          .onClick(() => {
            this.pageStack.pushPathByName('SecondPage', null)
          })
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
    }
    .title("Index")
    .mode(NavigationMode.Stack)
    .hideTitleBar(true)
    .hideBackButton(true)
    .ignoreLayoutSafeArea()
    .navDestination(this.PageMap)
  }

  @Builder
  PageMap(name: string) {
    if (name === 'SecondPage') {
      SecondPageBuilder()
    }
  }
}
Enter fullscreen mode Exit fullscreen mode 
@Component
struct SecondPage {
  @Consume('NavPathStack') pageStack: NavPathStack
  build() {
    NavDestination() {
      Column() {
        Text('Second Page')
          .fontSize(24)
          .fontWeight(FontWeight.Bold)
          .fontColor(Color.Black)
      }
      .align(Alignment.Center)
      .justifyContent(FlexAlign.Center)
    }
    .hideTitleBar(true)
    .width('100%')
    .height('100%')
  }
}

@Builder
export function SecondPageBuilder() {
  SecondPage()
}
Enter fullscreen mode Exit fullscreen mode

Tips & Tricks

🧠 Pro Tip:
When building multi-page apps, always keep your navigation state local using @Provide and @Consume.
This makes page transitions predictable and prevents memory leaks.

  • You can add parameters to your pages by passing data as the second argument to .pushPathByName(pageName, params).
  • Use .mode(NavigationMode.Stack) for classic stack (push/pop) navigation, or explore other modes for tab-based layouts.

Common Mistakes to Avoid

  • Directly using router: Don’t mix router and Navigation in the same app — pick one, preferably Navigation.
  • Not using .navDestination(): Your page mapping logic should be centralized.
  • Forgetting to use @Provide/@Consume: Navigation stack won’t work across pages without it.

Media Example

Navigation stack demo: Tap the button to navigate from Index to SecondPage and back!

Conclusion

Switching from router to the new Navigation component in ArkTS simplifies page management, provides better UX, and prepares your HarmonyOS app for advanced navigation scenarios in 2025 and beyond.
Try the sample above, extend it with your own pages, and you’ll see how easy it is to scale your project!

References

Huawei ArkTS Navigation Docs

Written by Muhammet Cagri Yilmaz

Top comments (0)