Layout Properties #

Margins #

The four margin properties (marginTop, marginRight, marginBottom and marginLeft) describe the distance between a view and its parent.

When you set margins through XML, you can choose between the following approaches.

• Set one value: Provide a single value that will be applied on all sides of the view.
• Set two values: Provide two values. The first value is applied to the top side, the second value is applied to the right side. Next, the first value is applied to the bottom and the second value to the left side (in that order).
• Set four values: Provide four values for each margin. The first value is applied to the top, the second value is applied to the right, the third value is applied to the bottom and the fourth value is applied to the left side (in that order).

Paddings #

The four padding properties (paddingTop, paddingRight, paddingBottom and paddingLeft) describe the distance between the layout container and its children.

When you set paddings through XML, you can choose between the following approaches.

• Set one value: Provide a single value that will be applied on all sides of the view.
• Set two values: Provide two values. The first value is applied to the top side, the second value is applied to the right side. Next, the first value is applied to the bottom and the second value to the left side (in that order).
• Set four values: Provide four values for each padding. The first value is applied to the top, the second value is applied to the right, the third value is applied to the bottom and the fourth value is applied to the left side (in that order).

Alignments #

Layout applies horizontal and vertical alignment only when an element is allocated more size than it needs.

The following table shows the valid values of horizontalAlignment.

The following table shows the valid values of verticalAlignment.

Percentage Support #

NativeScript supports percentage values for width, height and margin. When a layout pass begins, first the percent values are calculated based on parent available size. This means that on vertical StackLayout if you place two Buttons with height='50%' they will get all the available height (e.g., they will fill the StackLayout vertically.). The same applies for margin properties. For example, if you set marginLeft='5%', the element will have a margin that corresponds to 5% of the parent's available width.

iOS Safe Area Support #

The iOS Safe Area is a term that Apple introduced in iOS 11. It is the area of the screen that is free to use and won’t be obstructed by hardware and software parts of the system. The safe area is not a constant. It is affected by the notch, the rounded corners of the screen, the status bar and the home indicator, but also from parts of your application like the action bar and the tab bar. To get a better understanding refer to the Apple docs.

Since version 5.0 NativeScript provides a default handling mechanism for the iOS Safe Area. The default behavior is that certain container View components (these that can have children) overflow the safe area and are laid out to the edges of the screen. These container components are:

• Layouts
• ListView
• ScrollView
• WebView
• Repeater

Internally, the workflow is as follows:

1. Measure pass - all components are measured in the safe area portion of the screen.
2. Layout pass - all components are laid out in full screen, but are inset to the safe area boundaries.
3. Layout pass - if the component borders the safe area, it is adjusted and expanded to the edges of the screen.

iosOverflowSafeArea Property #

The above default behavior should provide good UX out of the box. Additionally, NativeScript 5.0 exposes a property iosOverflowSafeArea that can control how components handle the iOS Safe Area. Set this property value to true if you want the component to expand to the edges of the screen when it borders the safe area. Set it to false to explicitly prevent this behavior. The default value for container components is true. All other components are considered content that should be constrained to the safe area and default to false.

Layout Containers #

AbsoluteLayout #

The <AbsoluteLayout> container is the simplest layout container in NativeScript.

<AbsoluteLayout> has the following behavior:

• Uses a pair of absolute left/top coordinates to position its children.
• Doesn't enforce any layout constraints on its children.
• Doesn't resize its children at runtime when its size changes.

Example: a grid-like layout #

The following example creates a simple grid. For more information about creating grid layouts, see GridLayout.

<AbsoluteLayout backgroundColor="#3c495e">
  <label
    text="10,10"
    left="10"
    top="10"
    width="100"
    height="100"
    backgroundColor="#43b883"
  />
  <label
    text="120,10"
    left="120"
    top="10"
    width="100"
    height="100"
    backgroundColor="#43b883"
  />
  <label
    text="10,120"
    left="10"
    top="120"
    width="100"
    height="100"
    backgroundColor="#43b883"
  />
  <label
    text="120,120"
    left="120"
    top="120"
    width="100"
    height="100"
    backgroundColor="#43b883"
  />
</AbsoluteLayout>

Example: Overlapping elements #

The following example creates a group of overlapping items.

<AbsoluteLayout backgroundColor="#3c495e">
  <label
    text="10,10"
    left="10"
    top="10"
    width="100"
    height="100"
    backgroundColor="#289062"
  />
  <label
    text="30,40"
    left="30"
    top="40"
    width="100"
    height="100"
    backgroundColor="#43b883"
  />
</AbsoluteLayout>

Props #

Additional children props #

When an element is a direct child of <AbsoluteLayout>, you can set the following additional properties.

DockLayout #

<DockLayout> is a layout container that lets you dock child elements to the sides or the center of the layout.

<DockLayout> has the following behavior:

• Uses the dock property to dock its children to the left, right, top, bottom or center of the layout.
  To dock a child element to the center, it must be the last child of the container and you must set the stretchLastChild property of the parent to true.
• Enforces layout constraints to its children.
• Resizes its children at runtime when its size changes.

Example: Dock to every side without stretching the last child #

The following example creates a frame-like layout consisting of 4 elements, position at the 4 edges of the screen.

<DockLayout stretchLastChild="false" backgroundColor="#3c495e">
  <label text="left" dock="left" width="40" backgroundColor="#43b883" />
  <label text="top" dock="top" height="40" backgroundColor="#289062" />
  <label text="right" dock="right" width="40" backgroundColor="#43b883" />
  <label text="bottom" dock="bottom" height="40" backgroundColor="#289062" />
</DockLayout>

Example: Dock to every side and stretch the last child #

The following example shows how stretchLastChild affects the positioning of child elements in a DockLayout container. The last child (bottom) is stretched to take up all the remaining space after positioning the first three elements.

<DockLayout stretchLastChild="true" backgroundColor="#3c495e">
  <label text="left" dock="left" width="40" backgroundColor="#43b883" />
  <label text="top" dock="top" height="40" backgroundColor="#289062" />
  <label text="right" dock="right" width="40" backgroundColor="#43b883" />
  <label text="bottom" dock="bottom" backgroundColor="#1c6b48" />
</DockLayout>

Example: Dock to every side and the center #

The following example creates a <DockLayout> of 5 elements. The first four wrap the center element in a frame.

<DockLayout stretchLastChild="true" backgroundColor="#3c495e">
  <label text="left" dock="left" width="40" backgroundColor="#43b883" />
  <label text="top" dock="top" height="40" backgroundColor="#289062" />
  <label text="right" dock="right" width="40" backgroundColor="#43b883" />
  <label text="bottom" dock="bottom" height="40" backgroundColor="#289062" />
  <label text="center" backgroundColor="#1c6b48" />
</DockLayout>

Example: Dock multiple children to the same side #

The following example creates a single line of 4 elements that stretch across the entire height and width of the screen.

<DockLayout stretchLastChild="true" backgroundColor="#3c495e">
  <label text="left 1" dock="left" width="40" backgroundColor="#43b883" />
  <label text="left 2" dock="left" width="40" backgroundColor="#289062" />
  <label text="left 3" dock="left" width="40" backgroundColor="#1c6b48" />
  <label text="last child" backgroundColor="#43b883" />
</DockLayout>

Props #

Additional children props #

When an element is a direct child of <DockLayout>, you can set the following additional properties.

GridLayout #

<GridLayout> is a layout container that lets you arrange its child elements in a table-like manner.

The grid consists of rows, columns, and cells. A cell can span one or more rows and one or more columns. It can contain multiple child elements which can span over multiple rows and columns, and even overlap each other.

By default, <GridLayout> has one column and one row. You can add columns and rows by configuring the columns and the rows properties. In these properties, you need to set the number of columns and rows and their width and height. You set the number of columns by listing their widths, separated by a comma. You set the number of rows by listing their heights, separated by a comma.

You can set a fixed size for column width and row height or you can create them in a responsive manner:

• An absolute number: Indicates a fixed size.
• auto: Makes the column as wide as its widest child or makes the row as tall as its tallest child.
• *: Takes as much space as available after filling all auto and fixed size columns or rows.

See Props for more information.

Example: Grid layout with fixed sizing #

The following example creates a simple 2-by-2 grid with fixed column widths and row heights.

<GridLayout columns="115, 115" rows="115, 115">
  <label text="0,0" row="0" col="0" backgroundColor="#43b883" />
  <label text="0,1" row="0" col="1" backgroundColor="#1c6b48" />
  <label text="1,0" row="1" col="0" backgroundColor="#289062" />
  <label text="1,1" row="1" col="1" backgroundColor="#43b883" />
</GridLayout>

Example: Grid layout with star sizing #

The following example creates a grid with responsive design, where space is allotted proportionally to child elements.

<GridLayout columns="*, 2*" rows="2*, 3*" backgroundColor="#3c495e">
  <label text="0,0" row="0" col="0" backgroundColor="#43b883" />
  <label text="0,1" row="0" col="1" backgroundColor="#1c6b48" />
  <label text="1,0" row="1" col="0" backgroundColor="#289062" />
  <label text="1,1" row="1" col="1" backgroundColor="#43b883" />
</GridLayout>

Example: Grid layout with fixed and auto sizing #

The following example create a grid with one auto-sized column and one column with fixed size. Rows have a fixed height.

<GridLayout columns="80, auto" rows="80, 80" backgroundColor="#3c495e">
  <label text="0,0" row="0" col="0" backgroundColor="#43b883" />
  <label text="0,1" row="0" col="1" backgroundColor="#1c6b48" />
  <label text="1,0" row="1" col="0" backgroundColor="#289062" />
  <label text="1,1" row="1" col="1" backgroundColor="#43b883" />
</GridLayout>

Example: Grid layout with mixed sizing and merged cells #

The following example creates a complex grid with responsive design, mixed width and height settings, and some merged cells.

<GridLayout columns="40, auto, *" rows="40, auto, *" backgroundColor="#3c495e">
  <label text="0,0" row="0" col="0" backgroundColor="#43b883" />
  <label text="0,1" row="0" col="1" colSpan="2" backgroundColor="#1c6b48" />
  <label text="1,0" row="1" col="0" rowSpan="2" backgroundColor="#289062" />
  <label text="1,1" row="1" col="1" backgroundColor="#43b883" />
  <label text="1,2" row="1" col="2" backgroundColor="#289062" />
  <label text="2,1" row="2" col="1" backgroundColor="#1c6b48" />
  <label text="2,2" row="2" col="2" backgroundColor="#43b883" />
</GridLayout>

Props #

Additional children props #

When an element is a direct child of <GridLayout>, you can work with the following additional properties.

StackLayout #

<StackLayout> is a layout container that lets you stack the child elements vertically (default) or horizontally.

Example: Default stacking #

The following example creates a vertical stack of 3 equally-sized elements. Items are stretched to cover the entire width of the screen. Items are placed in the order they were declared in.

<StackLayout backgroundColor="#3c495e">
  <label text="first" height="70" backgroundColor="#43b883" />
  <label text="second" height="70" backgroundColor="#289062" />
  <label text="third" height="70" backgroundColor="#1c6b48" />
</StackLayout>

Example: Horizontal stacking #

The following example creates a horizontal stack of 3 equally-sized elements. Items are stretched to cover the entire height of the screen. Items are placed in the order they were declared in.

<StackLayout orientation="horizontal" backgroundColor="#3c495e">
  <label text="first" width="70" backgroundColor="#43b883" />
  <label text="second" width="70" backgroundColor="#289062" />
  <label text="third" width="70" backgroundColor="#1c6b48" />
</StackLayout>

Example: Stack layout with horizontally aligned children #

The following example creates a diagonal stack of items with responsive sizes. Items are vertically stacked.

<StackLayout backgroundColor="#3c495e">
  <label
    text="left"
    horizontalAlignment="left"
    width="33%"
    height="70"
    backgroundColor="#43b883"
  />
  <label
    text="center"
    horizontalAlignment="center"
    width="33%"
    height="70"
    backgroundColor="#289062"
  />
  <label
    text="right"
    horizontalAlignment="right"
    width="33%"
    height="70"
    backgroundColor="#1c6b48"
  />
  <label
    text="stretch"
    horizontalAlignment="stretch"
    height="70"
    backgroundColor="#43b883"
  />
</StackLayout>

Example: Horizontal stack layout with vertically aligned children #

The following example creates a diagonal stack of items with responsive sizes. Items are horizontally stacked.

<StackLayout orientation="horizontal" backgroundColor="#3c495e">
  <label
    text="top"
    verticalAlignment="top"
    width="70"
    height="33%"
    backgroundColor="#43b883"
  />
  <label
    text="center"
    verticalAlignment="center"
    width="70"
    height="33%"
    backgroundColor="#289062"
  />
  <label
    text="bottom"
    verticalAlignment="bottom"
    width="70"
    height="33%"
    backgroundColor="#1c6b48"
  />
  <label
    text="stretch"
    verticalAlignment="stretch"
    width="70"
    backgroundColor="#43b883"
  />
</StackLayout>

Props #

Additional children props #

None.

RootLayout #

<RootLayout> is a layout container designed to be used as the primary root layout container for your app with a built in api to easily control dynamic view layers. It extends a GridLayout so has all the features of a grid but enhanced with additional apis.

It's api can be observed here:

export class RootLayout extends GridLayout {
  open(view: View, options?: RootLayoutOptions): Promise<void>
  close(view: View, exitTo?: TransitionAnimation): Promise<void>
  bringToFront(view: View, animated?: boolean): Promise<void>
  closeAll(): Promise<void>
  getShadeCover(): View
}

export function getRootLayout(): RootLayout

export interface RootLayoutOptions {
  shadeCover?: ShadeCoverOptions
  animation?: {
    enterFrom?: TransitionAnimation
    exitTo?: TransitionAnimation
  }
}

export interface ShadeCoverOptions {
  opacity?: number
  color?: string
  tapToClose?: boolean
  animation?: {
    enterFrom?: TransitionAnimation // only applied if first one to be opened
    exitTo?: TransitionAnimation // only applied if last one to be closed
  }
  ignoreShadeRestore?: boolean
}

export interface TransitionAnimation {
  translateX?: number
  translateY?: number
  scaleX?: number
  scaleY?: number
  rotate?: number // in degrees
  opacity?: number
  duration?: number // in milliseconds
  curve?: any // CoreTypes.AnimationCurve (string, cubicBezier, etc.)
}

You can use getRootLayout() to get a reference to the root layout in your app from anywhere.

Example: RootLayout setup #

Sample layout:

<RootLayout height="100%" width="100%">
  <GridLayout height="100%">
    <label
      verticalAlignment="center"
      textAlignment="center"
      text="MAIN CONTENT AREA"
    ></label>
  </GridLayout>
</RootLayout>

Sample api usage:

// Open a dynamic popup
const view = this.getPopup('#EA5936', 110, -30)
getRootLayout()
  .open(view, {
    shadeCover: {
      color: '#000',
      opacity: 0.7,
      tapToClose: true
    },
    animation: {
      enterFrom: {
        opacity: 0,
        translateY: 500,
        duration: 500
      },
      exitTo: {
        opacity: 0,
        duration: 300
      }
    }
  })
  .catch(ex => console.error(ex))

// Close the dynamic popup
getRootLayout()
  .close(view, {
    opacity: 0,
    translate: { x: 0, y: -500 }
  })
  .catch(ex => console.error(ex))

function getPopup(color: string, size: number, offset: number): View {
  const layout = new StackLayout()
  layout.height = size
  layout.width = size
  layout.marginTop = offset
  layout.marginLeft = offset
  layout.backgroundColor = color
  layout.borderRadius = 10
  return layout
}

You can play with the toolbox app here

You can also find a more thorough example in this sample repo

WrapLayout #

<WrapLayout> is a layout container that lets you position items in rows or columns, based on the orientation property. When the space is filled, the container automatically wraps items onto a new row or column.

Example: Default wrap layout #

The following example creates a row of equally-sized items. When the row runs out of space, the container wraps the last item to a new row.

<WrapLayout backgroundColor="#3c495e">
  <label text="first" width="30%" height="30%" backgroundColor="#43b883" />
  <label text="second" width="30%" height="30%" backgroundColor="#1c6b48" />
  <label text="third" width="30%" height="30%" backgroundColor="#289062" />
  <label text="fourth" width="30%" height="30%" backgroundColor="#289062" />
</WrapLayout>

Example: Vertical wrap layout #

The following example creates a column of equally-sized items. When the row runs out of space, the container wraps the last item to a new column.

<WrapLayout orientation="vertical" backgroundColor="#3c495e">
  <label text="first" width="30%" height="30%" backgroundColor="#43b883" />
  <label text="second" width="30%" height="30%" backgroundColor="#1c6b48" />
  <label text="third" width="30%" height="30%" backgroundColor="#289062" />
  <label text="fourth" width="30%" height="30%" backgroundColor="#289062" />
</WrapLayout>

Props #

Additional children props #

None.

FlexboxLayout #

<FlexboxLayout> is a layout container that provides a non-exact implementation of the CSS Flexbox layout. This layout lets you arrange child components both horizontally and vertically.

Example: Default flex layout #

The following example creates a row of three equally-sized elements that span across the entire height of the screen.

<FlexboxLayout backgroundColor="#3c495e">
  <label text="first" width="70" backgroundColor="#43b883" />
  <label text="second" width="70" backgroundColor="#1c6b48" />
  <label text="third" width="70" backgroundColor="#289062" />
</FlexboxLayout>

Example: Column flex layout #

The following example creates a column of three equally-sized elements that span across the entire width of the screen.

<FlexboxLayout flexDirection="column" backgroundColor="#3c495e">
  <label text="first" height="70" backgroundColor="#43b883" />
  <label text="second" height="70" backgroundColor="#1c6b48" />
  <label text="third" height="70" backgroundColor="#289062" />
</FlexboxLayout>

Example: Row flex layout with items aligned to flex-start #

The following example creates a row of three items placed at the top of the screen. Items are placed in the order they were declared in.

<FlexboxLayout alignItems="flex-start" backgroundColor="#3c495e">
  <label text="first" width="70" height="70" backgroundColor="#43b883" />
  <label text="second" width="70" height="70" backgroundColor="#1c6b48" />
  <label text="third" width="70" height="70" backgroundColor="#289062" />
</FlexboxLayout>

Example: Row flex layout with custom order #

The following example creates a row of three items placed at the top of the screen. Items are placed in a customized order.

<FlexboxLayout alignItems="flex-start" backgroundColor="#3c495e">
  <label text="first" order="2" width="70" height="70" backgroundColor="#43b883" />
  <label text="second" order="3" width="70" height="70" backgroundColor="#1c6b48" />
  <label text="third" order="1" width="70" height="70" backgroundColor="#289062" />
</FlexboxLayout>

Example: Row flex layout with wrapping #

The following example creates four items with enabled line wrapping. When the row runs out of space, the container wraps the last item on a new line.

<FlexboxLayout flexWrap="wrap" backgroundColor="#3c495e">
  <label text="first" width="30%" backgroundColor="#43b883" />
  <label text="second" width="30%" backgroundColor="#1c6b48" />
  <label text="third" width="30%" backgroundColor="#289062" />
  <label text="fourth" width="30%" backgroundColor="#289062" />
</FlexboxLayout>

Example: Column flex layout with reverse order and items with a different alignSelf #

The following example shows how to use:

• flexDirection to place items in a column, starting from the bottom.
• justifyContent to create equal spacing between the vertically placed items.
• alignSelf to modify the position of items across the main axis.

<FlexboxLayout
  flexDirection="column-reverse"
  justifyContent="space-around"
  backgroundColor="#3c495e"
>
  <label text="first" height="70" backgroundColor="#43b883" />
  <label
    text="second"
    alignSelf="center"
    width="70"
    height="70"
    backgroundColor="#1c6b48"
  />
  <label
    text="third\nflex-end"
    alignSelf="flex-end"
    width="70"
    height="70"
    backgroundColor="#289062"
  />
  <label text="fourth" height="70" backgroundColor="#289062" />
</FlexboxLayout>

Props #

Additional children props #

When an element is a direct child of <FlexboxLayout>, you can work with the following additional properties.

Components #

ActionBar #

The ActionBar is NativeScript’s abstraction over the Android ActionBar and iOS NavigationBar. It represents a toolbar at the top of the activity window, and can have a title, application-level navigation, as well as other custom interactive items.

Example: Simple ActionBar with title #

<ActionBar title="ActionBar Title" />

<actionBar title="ActionBar Title" />

<ActionBar title="ActionBar Title" />

<ActionBar title="ActionBar Title"> </ActionBar>

<actionBar title="ActionBar Title" />

Example: ActionBar with custom title view #

<actionBar>
  <stackLayout nodeRole="titleView" orientation="horizontal">
    <image src="res://icon" width={40} height={40} verticalAlignment="center" />
    <label text="NativeScript" fontSize={24} verticalAlignment="center" />
  </stackLayout>
</actionBar>

<ActionBar>
  <StackLayout orientation="horizontal">
    <image src="res://icon" width="40" height="40" verticalAlignment="center" />
    <label text="ActionBar Title" fontSize="24" verticalAlignment="center" />
  </StackLayout>
</ActionBar>

<ActionBar>
  <StackLayout orientation="horizontal">
    <Image src="res://icon" width="40" height="40" verticalAlignment="center" />
    <Label text="ActionBar Title" fontSize="24" verticalAlignment="center" />
  </StackLayout>
</ActionBar>

<ActionBar>
  <StackLayout orientation="horizontal">
    <image src="res://icon" width="40" height="40" verticalAlignment="center"></image>
    <label text="ActionBar Title" fontSize="24" verticalAlignment="center"></label>
  </StackLayout>
</ActionBar>

<actionBar>
  <stackLayout orientation="horizontal">
    <image src="res://icon" width="40" height="40" verticalAlignment="center" />
    <label text="ActionBar Title" fontSize="24" verticalAlignment="center" />
  </stackLayout>
</actionBar>

Example: ActionBar with ActionItem #

The <ActionItem> components are supporting the platform-specific position and systemIcon for iOS and Android.

• Android sets position via android.position:

  • actionBar: Puts the item in the ActionBar. Action item can be rendered both as text or icon.
  • popup: Puts the item in the options menu. Items will be rendered as text.
  • actionBarIfRoom: Puts the item in the ActionBar if there is room for it. Otherwise, puts it in the options menu.

• iOS sets position via ios.position:

  • left: Puts the item on the left side of the ActionBar.
  • right: Puts the item on the right side of the ActionBar.

<actionBar title="ActionBar Title">
  <actionItem
    on:tap="{onTapShare}"
    ios.systemIcon="9"
    ios.position="left"
    android.systemIcon="ic_menu_share"
    android.position="actionBar"
  />
  <actionItem
    on:tap="{onTapDelete}"
    ios.systemIcon="16"
    ios.position="right"
    text="delete"
    android.position="popup"
  />
</actionBar>

<ActionBar title="ActionBar Title">
  <ActionItem
    @tap="onTapShare"
    ios.systemIcon="9"
    ios.position="left"
    android.systemIcon="ic_menu_share"
    android.position="actionBar"
  />
  <ActionItem
    @tap="onTapDelete"
    ios.systemIcon="16"
    ios.position="right"
    text="delete"
    android.position="popup"
  />
</ActionBar>

<actionBar title="ActionBar Title">
  <actionItem
    nodeRole="actionItems"
    onTap={onTapShare}
    ios={{
      systemIcon: 9,
      position: 'left' as const
    }}
    android={{
      systemIcon: 'ic_menu_share' as const,
      position: 'actionBar' as const
    }}
  />
  <actionItem
    nodeRole="actionItems"
    onTap={onTapDelete}
    ios={{
      systemIcon: 16,
      position: 'right' as const
    }}
    android={{
      position: 'popup' as const
    }}
    text="delete"
  />
</actionBar>

<ActionBar title="ActionBar Title">
  <ActionItem
    tap="onShare()"
    ios.systemIcon="9"
    ios.position="left"
    android.systemIcon="ic_menu_share"
    android.position="actionBar"
  >
  </ActionItem>
  <ActionItem
    text="delete"
    tap="onDelete()"
    ios.systemIcon="16"
    ios.position="right"
    android.position="popup"
  >
  </ActionItem>
</ActionBar>

<ActionBar title="ActionBar Title">
  <ActionItem
    (tap)="onShare()"
    ios.systemIcon="9"
    ios.position="left"
    android.systemIcon="ic_menu_share"
    android.position="actionBar"
  >
  </ActionItem>
  <ActionItem
    text="delete"
    (tap)="onDelete()"
    ios.systemIcon="16"
    ios.position="right"
    android.position="popup"
  >
  </ActionItem>
</ActionBar>

Example: ActionBar with NavigationButton #

<NavigationButton> is a UI component that provides an abstraction for the Android navigation button and the iOS back button.

<ActionBar title="ActionBar Title">
  <NavigationButton text="Go back" android.systemIcon="ic_menu_back" @tap="goBack" />
</ActionBar>

<actionBar title="ActionBar Title">
  <navigationButton
    nodeRole="navigationButton"
    text="Go back"
    android={{
      position: undefined,
      systemIcon: 'ic_menu_back'
    }}
    onTap={goBack}
  />
</actionBar>

<actionBar title="ActionBar Title">
  <navigationButton text="Go back" android.systemIcon="ic_menu_back" on:tap="{goBack}" />
</actionBar>

<ActionBar title="ActionBar Title">
  <NavigationButton text="Go back" android.systemIcon="ic_menu_back" tap="goBack" />
</ActionBar>

<ActionBar title="ActionBar Title">
  <NavigationButton
    text="Go back"
    android.systemIcon="ic_menu_back"
    (tap)="goBack()"
  ></NavigationButton>
</ActionBar>

Example: Setting an app icon for Android in ActionBar #

<ActionBar
  title="ActionBar Title"
  android.icon="res://icon"
  android.iconVisibility="always"
/>

<actionBar
  title="ActionBar Title"
  android.icon="res://icon"
  android.iconVisibility="always"
/>

<actionBar
  title="ActionBar Title"
  android={{ icon: 'res://icon', iconVisibility: 'always' }}
/>

<ActionBar
  title="ActionBar Title"
  android.icon="res://icon"
  android.iconVisibility="always"
/>

<ActionBar
  title="ActionBar Title"
  android.icon="res://icon"
  android.iconVisibility="always"
>
</ActionBar>

Example: Removing the border from ActionBar #

By default, a border is drawn at the bottom of the <ActionBar>. In addition to the border, on iOS devices a translucency filter is also applied over the <ActionBar>.

To remove this styling from your app, you can set the flat property to true.

<ActionBar title="ActionBar Title" flat="true" />

<actionBar title="ActionBar Title" flat="true" />

<actionBar title="ActionBar Title" flat={true} />

<ActionBar title="ActionBar Title" flat="true" />

<ActionBar title="ActionBar Title" flat="true"> </ActionBar>

Example: Styling ActionBar #

To style the <ActionBar>, you can use only background-color and color properties. Alternatively, you can use @nativescript/theme and use the default styles for each different theme. The icon property of ActionItem can use Icon Fonts with the font:// prefix. By setting up this prefix, a new image will be generated, which will be set as an <ActionItem>'s icon resource. While using this functionality, we need to specify the font-size, which will calculate the size of the generated image base on the device's dpi.

<!-- The default background-color and color of ActionBar & ActionItem are set through nativescript-theme (if used)-->
<ActionBar title="ActionBar Title">
  <!-- Explicitly hiding the NavigationBar to prevent the default one on iOS-->
  <NavigationButton visibility="collapsed"></NavigationButton>

  <!-- Using the icon property and Icon Fonts -->
  <ActionItem
    position="left"
    icon="font://&#xf0a8;"
    class="fas"
    (tap)="goBack()"
  ></ActionItem>

  <!-- Creating custom views for ActionItem-->
  <ActionItem ios.position="right">
    <GridLayout width="100">
      <button text="Theme" class="-primary -rounded-lg"></button>
    </GridLayout>
  </ActionItem>
</ActionBar>

<!-- The default background-color and color of ActionBar & ActionItem are set through nativescript-theme (if used)-->
<ActionBar title="ActionBar Title">
  <!-- Explicitly hiding the NavigationBar to prevent the default one on iOS-->
  <NavigationButton visibility="collapsed" />

  <!-- Using the icon property and Icon Fonts -->
  <ActionItem position="left" icon="font://&#xf0a8;" class="fas" tap="goBack" />

  <!-- Creating custom views for ActionItem-->
  <ActionItem ios.position="right">
    <GridLayout width="100">
      <button text="Theme" class="-primary -rounded-lg" />
    </GridLayout>
  </ActionItem>
</ActionBar>

Properties #

ActionBar Properties #

ActionItem Properties #

NavigationButton Properties #

Events #

API References #

Native Component #

Activity-Indicator #

<ActivityIndicator> is a UI component that shows a progress indicator signaling to the user of an operation running in the background.

<ActivityIndicator
  busy="{{ isBusy }}"
  busyChange="{{ onBusyChanged }}"
  loaded="indicatorLoaded"
/>

import { ActivityIndicator } from '@nativescript/core'

onBusyChanged(args: EventData) {
  const indicator: ActivityIndicator = args.object
  console.log(`indicator.busy changed to: ${indicator.busy}`)
}

<ActivityIndicator [busy]="isBusy" (busyChange)="onBusyChanged($event)">
</ActivityIndicator>

import { ActivityIndicator } from '@nativescript/core'

onBusyChanged(args: EventData) {
  const indicator: ActivityIndicator = args.object
  console.log(`indicator.busy changed to: ${indicator.busy}`)
}

<ActivityIndicator busy="true" @busyChange="onBusyChanged" />

export default {
  methods: {
    onBusyChanged(args) {
      const indicator = args.object // ActivityIndicator
      console.log(`indicator.busy changed to: ${indicator.busy}`)
    }
  }
}

<activityIndicator busy={true} />

<activityIndicator busy="{true}" on:busyChange="{onBusyChanged}" />

export default {
  methods: {
    onBusyChanged(args) {
      const indicator = args.object // ActivityIndicator
      console.log(`indicator.busy changed to: ${indicator.busy}`)
    }
  }
}

Props #

Events #

Native component #

Button #

<Button> is a UI component that displays a button which reacts to a user gesture.

For more information about the available gestures, see Gestures in the documentation.

<Button text="Tap me!" tap="onTap" />

import { Button } from '@nativescript/core'

export function onTap(args) {
  const button = args.object as Button
  // execute your custom logic here...
}

<button text="Tap me!" (tap)="onTap($event)"></button>

import { Button, EventData } from '@nativescript/core'

onTap(args: EventData) {
    const button = args.object as Button
    // execute your custom logic here...
}

<button text="Button" @tap="onButtonTap" />

<button text="Button" on:tap="{onButtonTap}" />

import { EventData } from '@nativescript/core'
;<button
  text="Button"
  onTap={(args: EventData) => {
    const button = args.object
  }}
/>

Props #

Events #

Styling the button #

If you need to style parts of the text, you can use a combination of a FormattedString and Span elements.

<button>
  <FormattedString>
    <span text="This text has a " />
    <span text="red " style="color: red" />
    <span text="piece of text. " />
    <span text="Also, this bit is italic, " fontStyle="italic" />
    <span text="and this bit is bold." fontWeight="bold" />
  </FormattedString>
</button>

Native component #

Date Picker #

<DatePicker> is a UI component that lets users select a date from a pre-configured range.

See also: TimePicker.

<DatePicker
  year="1980"
  month="4"
  day="20"
  loaded="onDatePickerLoaded"
  date="{{ date }}"
  minDate="{{ minDate }}"
  maxDate="{{ maxDate }}"
/>

import { DatePicker, EventData, Observable, Page } from '@nativescript/core'

export function onNavigatingTo(args: EventData) {
  const page = args.object as Page
  const vm = new Observable()

  // in the following example the DatePicker properties are binded via Observableproperties
  vm.set('minDate', new Date(1975, 0, 29)) // the binded minDate property accepts Date object
  vm.set('maxDate', new Date(2045, 4, 12)) // the binded maxDate property accepts Date object

  page.bindingContext = vm
}

export function onDatePickerLoaded(data: EventData) {
  const datePicker = data.object as DatePicker
  datePicker.on('dateChange', args => {
    console.dir(args)
  })
  datePicker.on('dayChange', args => {
    console.dir(args)
  })
  datePicker.on('monthChange', args => {
    console.dir(args)
  })
  datePicker.on('yearChange', args => {
    console.dir(args)
  })
}

<DatePicker
  year="1980"
  month="4"
  day="20"
  [minDate]="minDate"
  [maxDate]="maxDate"
  (dateChange)="onDateChanged($event)"
  (dayChange)="onDayChanged($event)"
  (monthChange)="onMonthChanged($event)"
  (yearChange)="onYearChanged($event)"
  (loaded)="onDatePickerLoaded($event)"
  verticalAlignment="center"
>
</DatePicker>

import { Component } from '@angular/core'
import { DatePicker } from '@nativescript/core'

@Component({
  moduleId: module.id,
  templateUrl: './usage.component.html'
})
export class DatePickerUsageComponent {
  minDate: Date = new Date(1975, 0, 29)
  maxDate: Date = new Date(2045, 4, 12)

  onDatePickerLoaded(args) {
    // const datePicker = args.object as DatePicker;
  }

  onDateChanged(args) {
    console.log('Date New value: ' + args.value)
    console.log('Date value: ' + args.oldValue)
  }

  onDayChanged(args) {
    console.log('Day New value: ' + args.value)
    console.log('Day Old value: ' + args.oldValue)
  }

  onMonthChanged(args) {
    console.log('Month New value: ' + args.value)
    console.log('Month Old value: ' + args.oldValue)
  }

  onYearChanged(args) {
    console.log('Year New value: ' + args.value)
    console.log('Year Old value: ' + args.oldValue)
  }
}

<DatePicker :date="someDate" />

<DatePicker v-model="selectedDate" />

import { EventData } from '@nativescript/core'
;<datePicker
  date={new Date()}
  onDateChange={(args: EventData) => {
    const datePicker = args.object
  }}
/>

<datePicker date="{someDate}" />

<datePicker bind:date="{selectedDate}" />

Props #

Events #

Native component #

Frame #

<Frame> is a UI component used to display <Page> elements. Every app needs at least a single <Frame> element, usually set as the root element.

A single root Frame #

new Vue({
  render: h => h('Frame', [h(HomePageComponent)])
})

Multiple Frames #

If you need to create multiple frames, you can do so by wrapping them in a Layout, for example if you want to have 2 frames side-by-side

<GridLayout columns="*, *">
  <frame col="0" />
  <frame col="1" />
</GridLayout>

<gridLayout columns={'* *'} rows={[]}>
  <frame col={0} />
  <frame col={1} />
</gridLayout>

<gridLayout columns="*, *">
  <frame col="0" />
  <frame col="1" />
</gridLayout>

Example: A frame with a default page #

<frame>
  <Page>
    <ActionBar title="Default Page Title" />
    <GridLayout>
      <label text="Default Page Content" />
    </GridLayout>
  </Page>
</frame>

<frame>
  <page>
    <actionBar title="Default Page Title" />
    <gridLayout>
      <label text="Default Page Content" />
    </gridLayout>
  </page>
</frame>

<frame>
  <page>
    <actionBar title="Default Page Title" />
    <gridLayout>
      <label text="Default Page Content" />
    </gridLayout>
  </page>
</frame>

Example: A frame with a default page from an external component #

<frame>
  <Page>
    <Home />
  </Page>
</frame>

import Home from './Home'

export default {
  components: {
    Home
  }
}

<frame>
  <Home />
</frame>

import Home from './Home.svelte'

import HomePage from './HomePage'

function AppContainer() {
  return (
    <frame>
      <HomePage />
    </frame>
  )
}

Native component #

HtmlView #

<HtmlView> is a UI component that lets you show static HTML content.

See also: WebView.

<HtmlView loaded="onHtmlLoaded" />

import { HtmlView } from '@nativescript/core'

export function onHtmlLoaded(args) {
  const myHtmlView = args.object as HtmlView
  myHtmlView.html = `<span>
        <h1><font color=\"blue\">NativeScript HtmlView</font></h1></br>
        <h3>This component accept simple HTML strings</h3></span>`
}

<HtmlView [html]="htmlString"></HtmlView>

import { Component } from '@angular/core'

@Component({
  moduleId: module.id,
  templateUrl: './usage.component.html'
})
export class HtmlViewUsageComponent {
  htmlString: string

  constructor() {
    this.htmlString = `<span>
                          <h1>HtmlView demo in <font color="blue">NativeScript</font> App</h1>
                        </span>`
  }
}

<HtmlView html="<div><h1>HtmlView</h1></div>" />

<htmlView html="<div><h1>HtmlView</h1></div>" />

<htmlView html="<div><h1>HtmlView</h1></div>" />

Props #

Native component #

Image #

<Image> is a UI component that shows an image from an ImageSource or from a URL.

Example: Displaying an image from App_Resources #

<Image src="res://icon" stretch="aspectFill" />

<image src="res://icon" stretch="aspectFill"> </image>

<image src="res://icon" stretch="aspectFill" />

<image src="res://icon" stretch="aspectFill" />

<image src="res://icon" stretch="aspectFill" />

Example: Displaying an image relative to the app directory #

<Image src="~/logo.png" stretch="aspectFill" />

<image src="~/logo.png" stretch="aspectFill"></image>

<image src="~/logo.png" stretch="aspectFill" />

<image src="~/logo.png" stretch="aspectFill" />

<image src="~/logo.png" stretch="aspectFill" />

Example: Displaying an image from a URL #

<Image
  src="https://art.nativescript.org/logo/export/NativeScript_Logo_Blue_White.png"
  stretch="aspectFill"
/>

<image
  src="https://art.nativescript.org/logo/export/NativeScript_Logo_Blue_White.png"
  stretch="aspectFill"
>
</image>

<image
  src="https://art.nativescript.org/logo/export/NativeScript_Logo_Blue_White.png"
  stretch="aspectFill"
/>

<image
  src="https://art.nativescript.org/logo/export/NativeScript_Logo_Blue_White.png"
  stretch="aspectFill"
/>

<image
  src="https://art.nativescript.org/logo/export/NativeScript_Logo_Blue_White.png"
  stretch="aspectFill"
/>

Example: Displaying a base64-encoded image #

<Image src="data:Image/png;base64,iVBORw..." stretch="aspectFill" />

<image src="data:Image/png;base64,iVBORw..." stretch="aspectFill"></image>

<image src="data:Image/png;base64,iVBORw..." stretch="aspectFill" />

<image src="data:Image/png;base64,iVBORw..." stretch="aspectFill" />

<image src="data:Image/png;base64,iVBORw..." stretch="aspectFill" />

Example: Image with CSS and an icon fonts #

<Image src="font://&#xf004;" class="fas" />

<image src="font://&#xf004;" class="fas"></image>

<image src="font://&#xf004;" class="fas" />

<image src.decode="font://&#xf004;" class="fas" />

<image src="font://&#xf004;" class="fas" />

Props #

Native component #

Label #

<Label> is a UI component that displays read-only text.

Example: Simple label #

<Label text="Label" />

<label text="Label"></label>

<label>Label</label>

<label text="Label" />

<label text="Label" />

Example: Styling the label #

If you need to style parts of the text, you can use a combination of a FormattedString and Span elements.

<Label textWrap="true">
  <FormattedString>
    <Span text="This text has a " />
    <Span text="red " style="color: red" />
    <Span text="piece of text. " />
    <Span text="Also, this bit is italic, " fontStyle="italic" />
    <Span text="and this bit is bold." fontWeight="bold" />
  </FormattedString>
</Label>