Page

<Page> is a UI component for representing screens that users are able to navigate to through a Frame. A Page itself can only contain a single child view with the exception of the ActionBar which has it's own special "slot".

<Page>
  <ActionBar title="MyApp" />

  <!-- the main content - must be a single view -->
  <GridLayout>
    <Label text="Main Content" />
  </GridLayout>
</Page>

Page Lifecycle ​

A page emits various events during navigation that you can use to update data/state in your app.

Lifecycle event examples ​

# frame.navigate(mainPage) - initial navigation
mainPage    > navigatingTo (isBackNavigation: false)
mainPage    > loaded
mainPage    > navigatedTo (isBackNavigation: false)

# frame.navigate(detailsPage)
mainPage    > navigatingFrom (isBackNavigation: false)
detailsPage > navigatingTo (isBackNavigation: false)
detailsPage > loaded
mainPage    > unloaded
mainPage    > navigatedFrom (isBackNavigation: false)
detailsPage > navigatedTo (isBackNavigation: false)

# frame.goBack()
detailsPage > navigatingFrom (isBackNavigation: true)
mainPage    > navigatingTo (isBackNavigation: true)
mainPage    > loaded
detailsPage > unloaded
detailsPage > navigatedFrom (isBackNavigation: true)
detailsPage > disposeNativeView # since it's no longer in the backstack
mainPage    > navigatedTo (isBackNavigation: true)

# frame.navigate(mainPage) - initial navigation
mainPage    > navigatingTo (isBackNavigation: false)
mainPage    > loaded
mainPage    > navigatedTo (isBackNavigation: false)

# frame.navigate(detailsPage, { clearHistory: true })
mainPage    > navigatingFrom (isBackNavigation: false)
detailsPage > navigatingTo (isBackNavigation: false)
detailsPage > loaded
mainPage    > unloaded
mainPage    > navigatedFrom (isBackNavigation: false)
mainPage    > disposeNativeView
detailsPage > navigatedTo (isBackNavigation: false)

# frame.goBack() - no-op, there's nothing in the backstack.

# frame.navigate(mainPage, { backstackVisible: false }) - initial navigation
mainPage    > navigatingTo (isBackNavigation: false)
mainPage    > loaded
mainPage    > navigatedTo (isBackNavigation: false)

# frame.navigate(detailsPage)
mainPage    > navigatingFrom (isBackNavigation: false)
detailsPage > navigatingTo (isBackNavigation: false)
detailsPage > loaded
mainPage    > unloaded
mainPage    > navigatedFrom (isBackNavigation: false)
mainPage    > disposeNativeView # since backstackVisible: false, we won't be able to reach mainPage after this point
detailsPage > navigatedTo (isBackNavigation: false)

Examples ​

Getting a reference to the current Page ​

NativeScript provides various ways to access the current Page instance.

Via Page Events ​

Any events emitted by the Page will have a reference to the Page itself via args.object. For example:

// loaded event
onPageLoaded(args: LoadEventData) {
  const page = args.object as Page;
}

// navigatedTo event
onNavigatedTo(args: NavigatedData) {
  const page = args.object as Page;
}

Via the page property of any View within the Page ​

Any View nested inside a Page hierarchy can access the Page via the page property.

onTap(args: EventData) {
  const button = args.object as Button
  const page = button.page as Page;
}

Via the currentPage property of a Frame instance ​

The currently displayed page can be accessed via the Frame, to get a reference to the frame you can use Frame.topmost() for example:

import { Frame } from '@nativescript/core'

const frame = Frame.topmost()
const page = frame.currentPage // Page

See Frame, Getting a Frame Instance.

Handling various Page events ​

A page emits various events during it's lifecycle, navigation events and general View events like loaded/unloaded/layoutChanged etc.

<Page
  loaded="onLoaded"
  unloaded="onUnloaded"
  navigatedFrom="onNavigatedFrom"
  navigatedTo="onNavigatedTo"
  navigatingFrom="onNavigatingFrom"
  navigatingTo="onNavigatingTo"
  layoutChanged="onLayoutChanged"
>
  <ActionBar title="MyApp" />
  <!-- ... -->
</Page>

onLoaded(args: EventData) {
  const page = args.object as Page
}

onUnloaded(args: EventData) {
  const page = args.object as Page
}

onLayoutChanged(args: EventData) {
  const page = args.object as Page
}

onNavigatedTo(args: NavigatedData) {
  const page = args.object as Page
  console.log(args.isBackNavigation)
}

onNavigatingFrom(args: NavigatedData) {
  const page = args.object as Page
  console.log(args.isBackNavigation)
}

onNavigatedFrom(args: NavigatedData) {
  const page = args.object as Page
  console.log(args.isBackNavigation)
}

Props ​

actionBar ​

actionBar: ActionBar

Gets or sets the ActionBar for this page.

See ActionBar.

actionBarHidden ​

actionBarHidden: boolean

Allows hiding the ActionBar.

Defaults to false.

frame ​

frame: Frame

The Frame instance containing the page.

See Frame.

navigationContext ​

navigationContext: any

A context used to pass data during navigation.

backgroundSpanUnderStatusBar ​

backgroundSpanUnderStatusBar: boolean

Gets or sets whether the background of the page spans under the status bar.

Defaults to false.

androidStatusBarBackground ​

androidStatusBarBackground: Color

Gets or sets the color of the status bar on Android devices. Android only.

See Color.

androidOverflowEdge ​

androidOverflowEdge:
  | 'none'
  | 'left'
  | 'top'
  | 'right'
  | 'bottom'
  | 'dont-apply'
  | 'left-dont-consume'
  | 'top-dont-consume'
  | 'right-dont-consume'
  | 'bottom-dont-consume'
  | 'all-but-left'
  | 'all-but-top'
  | 'all-but-right'
  | 'all-but-bottom'

Controls how Android system insets (status bar, navigation bar, cutouts) are applied and/or consumed by the Page. When insets are applied, they are added to the Page's padding. Insets propagate down the view hierarchy until consumed. Defaults to 'dont-apply' for Pages. Android only.

Options:

enableSwipeBackNavigation ​

enableSwipeBackNavigation: boolean

Gets or sets whether the page can be swiped back on iOS. iOS only.

Defaults to true.

statusBarStyle ​

statusBarStyle: 'light' | 'dark'

Gets or sets the style of the status bar.

...Inherited ​

For additional inherited properties, refer to the API Reference.

Events ​

loaded ​

on('loaded', (args: EventData) => {
  const page = args.object as Page
  console.log('Page loaded')
})

Emitted after the page has been loaded.

navigatingTo ​

on('navigatingTo', (args: NavigatedData) => {
  const page = args.object as Page
  console.log('Page is being navigated to:', args.isBackNavigation)
})

Emitted before the app has navigated to the current page.

navigatedTo ​

on('navigatedTo', (args: NavigatedData) => {
  const page = args.object as Page
  console.log('Page has been navigated to:', args.isBackNavigation)
})

Emitted after the app has navigated to the current page.

navigatingFrom ​

on('navigatingFrom', (args: NavigatedData) => {
  const page = args.object as Page
  console.log('Page is being navigated from:', args.isBackNavigation)
})

Emitted before the app has navigated away from the current page.

navigatedFrom ​

on('navigatedFrom', (args: NavigatedData) => {
  const page = args.object as Page
  console.log('Page has been navigated from:', args.isBackNavigation)
})

Emitted after the app has navigated away from the current page.

androidOverflowInset ​

on('androidOverflowInset', (args) => {
  // args.inset: { top, bottom, left, right, topConsumed?, bottomConsumed?, leftConsumed?, rightConsumed? }
})

Emitted when androidOverflowEdge is set to 'dont-apply', allowing manual handling of system insets. You can inspect and modify inset values and explicitly consume individual sides by setting the corresponding *Consumed flags. Android only.

Example:

page.on('androidOverflowInset', (args) => {
  // Modify inset values if needed
  args.inset.top += 10
  args.inset.bottom += 10
  args.inset.left += 10
  args.inset.right += 10

  // Explicitly consume each side
  args.inset.topConsumed = true
  args.inset.bottomConsumed = true
  args.inset.leftConsumed = true
  args.inset.rightConsumed = true
})

Android: Edge-to-Edge tip ​

import { Utils } from '@nativescript/core'

// Let the page handle insets manually
page.androidOverflowEdge = 'dont-apply'

// Enable edge-to-edge (Android) with light/dark colors
import { Application, Color } from '@nativescript/core'
const activity =
  Application.android.foregroundActivity || Application.android.startActivity
Utils.android.enableEdgeToEdge(activity, {
  statusBarLightColor: new Color('#FFFFFF'),
  statusBarDarkColor: new Color('#000000'),
})

// Optionally handle and consume insets yourself
page.on('androidOverflowInset', (args) => {
  args.inset.top += 8
  args.inset.bottom += 8
  args.inset.topConsumed = true
  args.inset.bottomConsumed = true
})

Native component ​

• Android: org.nativescript.widgets.GridLayout
• iOS: UIViewController