<Frame> is a UI component used to display and navigate between Pages. A NativeScript app can have multiple Frames, or none - most apps will have at least a single Frame often set as the the root view (or inside a RootLayout).

This example shows a single root frame that navigates to the main-page by default, and allows the user to navigate further within this frame (spanning the full-screen).

<!-- app-root -->
<Frame defaultPage="main-page"/>

This example shows an always visible menu bar stacked above a Frame that allows the user to navigate further.

<GridLayout rows="auto, *">
  <Label row="0" text="Example Menu Bar"/>
  <ContentView row="1">
    <Frame defaultPage="mainPage"/>
  </ContentView>
</GridLayout>

::: info Note We have wrapped the Frame inside a ContentView because on iOS a frame always spans the full height of it's parent container, so we wouldn't be able to resize it without the additional ContentView. :::

This pseudo example shows two Frames side-by-side, the frame on the left represents a list of conversations, and the Frame on the right represents the details of the currently selected conversation.

The idea of using a Frame on the left is to allow navigating to a different Page while keeping the conversation-details open on the right.

<GridLayout columns="300, *">
  <ContentView col="0">
    <Frame defaultPage="conversation-list" />
  </ContentView>
  <ContentView col="1">
    <Frame defaultPage="conversation-details" />
  </ContentView>
</GridLayout>

::: info Note This is a simplified example to convey the possibilities, in a real app implementation there would be nuances specific to the app. :::

actionBarVisibility: 'auto' | 'always' | 'never'

Used to control the visibility the Navigation Bar in iOS and the ActionBar in Android for all Pages within this Frame.

animated: boolean

Gets or sets if navigation transitions within this Frame should be animated.

backStack: BackstackEntry[]

Readonly list of backstack entries.

See BackstackEntry.

currentEntry: NavigationEntry

Readonly. The current NavigationEntry the Frame is navigated to.

See NavigationEntry.

currentPage: Page

Readonly. The current Page the Frame is navigated to.

See Page.

transition: NavigationTransition

Gets or sets the default navigation transition for this Frame.

See NavigationTransition.

defaultAnimatedNavigation: boolean

Static. Gets or sets if navigation transitions should be animated globally.

defaultTransition: NavigationTransition

Static. Gets or sets the default NavigationTransition for all frames across the app.

See NavigationTransition.

For additional inherited properties, refer to the API Reference.

canGoBack(): boolean

Returns wether or not this Frame can navigate back (there are entries in the backstack).

goBack(to?: BackstackEntry): void

Navigates to the previous entry (or to) in the backstack.

See BackstackEntry.

navigate(pageModuleName: string): void
// or
navigate(create: () => Page): void
// or
navigate(entry: NavigationEntry): void

Navigates to a Page.

See Frame.navigate Reference, Page, NavigationEntry.

getFrameById(id: string): Frame

Static. Returns a Frame by it's id if found.

See Frame.

topmost(): Frame

Static. Returns the topmost frame.

See Frame.

on('navigatingTo', (args: NavigationData) => {
  const frame = args.object as Frame
  const entry = args.entry as BackstackEntry
  const page = entry.resolvedPage as Page
})

Emitted when the Frame is navigating to a new Page.

on('navigatedTo', (args: NavigationData) => {
  const frame = args.object as Frame
  const entry = args.entry as BackstackEntry
  const page = entry.resolvedPage as Page
})

Emitted when the Frame has navigated to a new Page.

See NavigationTransition API Reference.

name: string

A named transition name. Available transitions:

• curl (same as curlUp) (iOS only)
• curlUp (iOS only)
• curlDown (iOS only)
• explode (Android only)
• fade
• flip (same as flipRight)
• flipRight
• flipLeft
• slide (same as slideLeft)
• slideLeft
• slideRight
• slideTop
• slideBottom

instance: Transition

This property allows you to define a custom transition instance

See Transition.

duration: number

The duration of the transition in milliseconds

curve: CoreTypes.AnimationCurve

Sets the transition animation curve.

Alternatively, you can pass an instance of type UIViewAnimationCurve for iOS or android.animation.TimeInterpolator for Android.

See CoreTypes.AnimationCurve.

See NavigationEntry API Reference.

moduleName: string

The name of the Page module to navigate to (eg. pages/details-page given a pages/details-page.xml exists).

create: () => View

A function called to create the Page (View instance) to be navigated to.

::: details Example

function create() {
  const page = new Page()
  const actionBar = new ActionBar()
  actionBar.title = 'Example Page'
  page.actionBar = actionBar

  const stackLayout = new StackLayout()
  stackLayout.backgroundColor = '#65adf1'
  page.content = stackLayout

  return page
}

:::

context: any

An object used to pass data to the navigated to Page.

transition: string | NavigationTransition

The transition name, or a NavigationTransition to use when navigating.

See NavigationTransition.

transitionAndroid: string | NavigationTransition

Overrides the transition property when navigating on Android.

See NavigationTransition.

transitioniOS: string | NavigationTransition

Overrides the transition property when navigating on iOS.

See NavigationTransition.

backstackVisible: boolean

If set to true, it records the navigation in the backstack.

If set to false, it navigates without affecting the backstack. Once navigated away from the Page, it will get disposed and the user can't navigate back to it (via the back button).

clearHistory: boolean

If set to true, it clears the navigation history backstack.

• Android: org.nativescript.widgets.ContentLayout
• iOS: UINavigationController
• Linux: a GtkFixed container that hosts the current page