📺 "One project. One language. Three apps." Learn more in our upcoming code sharing webinar!

NativeScript Core

Action Bar

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.

Basics

The title of the ActionBar can be easily set by its corresponding property - title. We can additionally set an icon to use in your ActionBar on Android with the icon property.

Here’s what a basic usage of the title and icon properties looks like:

<Page.actionBar>
    <ActionBar title="Basics"/>
</Page.actionBar>

Note: The icon can only be set in Android platform. It is hidden by default, but you can explicitly control its visibility with the `android.iconVisibility' property.

Furthermore, the title can be customized by placing a content component (button, label, layout-components, etc.) directly in the ActionBar.

Improve this document

Demo Source


Code Behind

The ActionBar can be dynamically created and controlled. The property navigationButton allows us to overwrite the default navigation button (if one is present). To explicitly show/hide an action bar on your page, use the actionBarHidden property of the current page.

const ActionBar = require("tns-core-modules/ui/action-bar").ActionBar;
const NavigationButton = require("tns-core-modules/ui/action-bar").NavigationButton;

function onLoaded(args) {
    const page = args.object;

    const newActionBar = new ActionBar();
    newActionBar.title = "Code-Behind ActionBar";
    const newNavigaitonButton = new NavigationButton();
    newNavigaitonButton.text = "Go Back";
    newActionBar.navigationButton = newNavigaitonButton;

    page.actionBar = newActionBar;
    page.actionBarHidden = false;
}
exports.onLoaded = onLoaded;
import { EventData } from "tns-core-modules/data/observable";
import { ActionBar, NavigationButton } from "tns-core-modules/ui/action-bar";
import { Page } from "tns-core-modules/ui/page";

export function onLoaded(args: EventData) {
    const page = <Page>args.object;

    const newActionBar = new ActionBar();
    newActionBar.title = "Code-Behind ActionBar";
    const newNavigaitonButton = new NavigationButton();
    newNavigaitonButton.text = "Go Back";
    newActionBar.navigationButton = newNavigaitonButton;

    page.actionBar = newActionBar;
    page.actionBarHidden = false;
}

iOS Specifics: The default text of the button is the title of the previous page; you can change it by setting the text property as shown in the example Setting the Text Title. In iOS, the back button is used explicitly for navigation. It navigates to the previous page and you cannot handle the tap event to override this behavior. If you want to place a button on the left side of the ActionBar and handle the tap event (e.g., show slide-out), you can use ActionItem with ios.position="left".

Android Specifics: In Android, you cannot set text inside the navigation button. You can use the icon property to set an image (e.g., ~\images\nav-image.png or res:\\ic_nav). You can use android.systemIcon to set one of the system icons available in Android. In this case, there is no default behaviour for NavigationButton's tap event, and we should define manually the callback function, which will be executed.

Improve this document

Demo Source


Creating Sidedrawer Button

This example shows how to implement a "show side-drawer button" functionality.

<Page.actionBar>
    <ActionBar title="SideDrawer Button">
        <android>
            <NavigationButton icon="res://menu" tap="showSideDrawer" />
        </android>
        <ios>
            <ActionItem icon="res://menu" ios.position="left" tap="showSideDrawer" />
        </ios>
    </ActionBar>
</Page.actionBar>

For Android, this example uses the NavigationButton because ActionItems are shown on the right side of the ActionBar.

For iOS, this code adds a regular ActionItem with position set to left. Using the NavigationButton as a side-drawer button in iOS is not possible, because its function is to always navigate back in the application.

Note: The <android> and <ios> tags are used inside the XML to define platform-specific elements. Important: The platform specific tags (<android> and <ios>) will work only in non-Angular based project.

Improve this document

Demo Source


Custom Title View

You could set a custom view, which will be rendered instead of the ActionItem text. The example below demonstrates, how to load to separate labels inside the item.

<Page.actionBar>
    <ActionBar title="test">
        <StackLayout orientation="horizontal"
            ios:horizontalAlignment="center"
            android:horizontalAlignment="left">
            <Image src="res://icon" class="action-image"></Image>
            <Label text="ativeScript"  class="action-label"></Label>
        </StackLayout>
    </ActionBar>
</Page.actionBar>

Improve this document

Demo Source


Hide Show Actionbar

You can explicitly control the visibility of the ActionBar by setting the actionBarHidden property of the Page.

<Page actionBarHidden="{{ abHidden }}" xmlns="http://www.nativescript.org/tns.xsd" navigatingTo="onNavigatingTo">
    <Page.actionBar>
        <ActionBar title="ActionBar"></ActionBar>
    </Page.actionBar>

    <StackLayout verticalAlignment="middle"> 
        <Button text="{{ abHidden ? 'Show ActionBar' : 'Hide ActionBar' }}" tap="onTap" textWrap="true" class="fa" />
    </StackLayout>
</Page>
const Observable = require("tns-core-modules/data/observable").Observable;
let value = false;

function onNavigatingTo(args) {
    const page = args.object;
    const vm = new Observable();
    vm.set("abHidden", value);
    page.bindingContext = vm;
}
exports.onNavigatingTo = onNavigatingTo;

function onTap(args) {
    const page = args.object.page;
    const vm = page.bindingContext;
    value = !value;
    vm.set("abHidden", value);
}
exports.onTap = onTap;
import { EventData, Observable } from "tns-core-modules/data/observable";
import { Button } from "tns-core-modules/ui/button";
import { Page } from "tns-core-modules/ui/page";
import { GestureEventData } from "tns-core-modules/ui/gestures";

let value: boolean = false;

export function onNavigatingTo(args: EventData) {
    const page = <Page>args.object;
    const vm = new Observable();
    vm.set("abHidden", value);
    page.bindingContext = vm;
}

export function onTap(args: GestureEventData) {
    const page = (<Button>args.object).page;
    const vm = page.bindingContext;
    value = !value;
    vm.set("abHidden", value);
}

In Android, the application bar is visible by default and shows the name of the application as title. The navigation button is visible only when it is explicitly defined in the application.

In iOS, if the application bar is empty (e.g., no title or action items are defined), it is hidden on the first page and automatically shown after navigation to host the navigation button. If the ActionBar is not empty (e.g., there is a title or action items defined) it will be shown on first page, too.

Improve this document

Demo Source


Hiding Action Items

You can use the visibility property of the ActionItem to dynamically hide and show items. You can also use binding for the visibility.

<Page.actionBar>
    <ActionBar title="Action Items Visibility">
        <ActionItem tap="onEdit" ios.systemIcon="2" android.systemIcon="ic_menu_edit" ios.position="right"
            visibility="{{ isEditing ? 'collapse' : 'visible' }}"/>
        <ActionItem tap="onSave" ios.systemIcon="3" android.systemIcon="ic_menu_save" ios.position="right"
            visibility="{{ isEditing ? 'visible' : 'collapse' }}"/>
        <ActionItem tap="onCancel"  ios.systemIcon="1" android.systemIcon="ic_menu_close_clear_cancel"
            visibility="{{ isEditing ? 'visible' : 'collapse' }}"/>
    </ActionBar>
</Page.actionBar>
const fromObject = require("tns-core-modules/data/observable").fromObject;
function onEdit(args) {
    const page = args.object.page;
    page.bindingContext.set("isEditing", true);
}
exports.onEdit = onEdit;

function onSave(args) {
    const page = args.object.page;
    page.bindingContext.set("isEditing", false);
}
exports.onSave = onSave;

function onCancel(args) {
    const page = args.object.page;
    page.bindingContext.set("isEditing", false);
}
exports.onCancel = onCancel;
import { EventData, fromObject } from "tns-core-modules/data/observable";
import { ActionItem } from "tns-core-modules/ui/action-bar";
import { Page } from "tns-core-modules/ui/page";
import { GestureEventData } from "tns-core-modules/ui/gestures";

export function onEdit(args: GestureEventData) {
    const page = (<ActionItem>args.object).page;
    page.bindingContext.set("isEditing", true);
}

export function onSave(args: GestureEventData) {
    const page = (<ActionItem>args.object).page;
    page.bindingContext.set("isEditing", false);
}

export function onCancel(args: GestureEventData) {
    const page = (<ActionItem>args.object).page;
    page.bindingContext.set("isEditing", false);
}

Here is an example of showing different action items when the app is in "editing" mode:

Improve this document

Demo Source


Items Actionbar

You can define additional action buttons using the actionItems collection:

<Page.actionBar>
    <ActionBar title="Action Items">
        <ActionItem tap="onShare"
            ios.systemIcon="9" ios.position="left"
            android.systemIcon="ic_menu_share" android.position="actionBar"></ActionItem>
        <ActionItem tap="onDelete" text="delete" 
            ios.systemIcon="16" ios.position="right"
            android.position="popup"></ActionItem>
    </ActionBar>
</Page.actionBar>
const fromObject = require("tns-core-modules/data/observable").fromObject;

exports.onNavigatingTo = function(args) {
    const page = args.object;
    page.bindingContext = fromObject({
        title: "Items \n\nDemonstrating action items properties and position"
    });
};

exports.onShare = function() {
    console.log("share tap");
};

exports.onDelete = function() {
    console.log("delete tap");
};
import { EventData, fromObject } from "tns-core-modules/data/observable";
import { Page } from "tns-core-modules/ui/page";
import { GestureEventData } from "tns-core-modules/ui/gestures";

export function onNavigatingTo(args: EventData) {
    const page = <Page>args.object;
    page.bindingContext = fromObject({
        title: "Items \n\nDemonstrating action items properties and position"
    });
}

export function onShare(args: GestureEventData) {
    console.log("Share tapped!");
}

export function onDelete(args: GestureEventData) {
    console.log("Delete tapped!");
}

Positioning

The following positioning options are available for iOS and Android.

Android (set with android.position):

  • actionBar[default]: 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 (set with ios.position):

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

Setting Icons

You can use the icon property to set an image instead of text for the action item. You can use local image (e.g., ~/images/add.png) or resource (e.g., res://ic_add). Because there is no way to explicitly set width and height for icons, the recommended approach is using resources.

You can use the android.systemIcon and ios.systemIcon properties to show system icons. If you define a system icon, it will be used instead of icon and text properties.

Values for android.systemIcon correspond to the resources names of the built-in Android system icons. For a full list of Android drawable names, you may visit Android Developer Site.

Values for ios.systemIcon are numbers from the UIBarButtonSystemItem enumeration:

Value Icon Value Icon
0 Done 12 Search
1 Cancel 13 Refresh
2 Edit 14 Stop
3 Save 15 Camera
4 Add 16 Trash
5 FlexibleSpace 17 Play
6 FixedSpace 18 Pause
7 Compose 19 Rewind
8 Reply 20 FastForward
9 Action 21 Undo
10 Organize 22 Redo
11 Bookmarks 23 PageCurl

Improve this document

Demo Source


The NavigationButton component is a common abstraction over the iOS back button and the Android navigation button.

<Page.actionBar>
    <ActionBar title="App Icon Demo">
        <NavigationButton text="Go Back" android.systemIcon="ic_menu_back" tap="onNavBtnTap"/>
    </ActionBar>
</Page.actionBar>
const fromObject = require("tns-core-modules/data/observable").fromObject;

exports.onNavigatingTo = function(args) {
    const page = args.object;
    page.bindingContext = fromObject({
        title: "ActionBar's Navigation Button demo"
    });
};

exports.onNavBtnTap = function(args) {
    // This code will be called only in Android.
    console.log("Navigation button tapped!");

    const navigationButton = args.object;
    const frame = navigationButton.page.frame;
    frame.goBack();
};
import { EventData, fromObject } from "tns-core-modules/data/observable";
import { NavigationButton } from "tns-core-modules/ui/action-bar";
import { Frame } from "tns-core-modules/ui/frame";
import { Page } from "tns-core-modules/ui/page";
import { GestureEventData } from "tns-core-modules/ui/gestures";

export function onNavigatingTo(args: EventData) {
    const page = <Page>args.object;
    page.bindingContext = fromObject({
        title: "ActionBar's Navigation Button demo"
    });
}

export function onNavBtnTap(args: GestureEventData) {
    // This code will be called only in Android.
    console.log("Navigation button tapped!");

    const navigationButton = <NavigationButton>args.object;
    const frame = <Frame>navigationButton.page.frame;
    frame.goBack();
}

iOS Specifics

The default text of the button is the title of the previous page; you can change it by setting the text property as shown in the example Setting the Text Title. In iOS, the back button is used explicitly for navigation. It navigates to the previous page and you cannot handle the tap event to override this behavior.

If you want to place a button on the left side of the ActionBar and handle the tap event (e.g., show slide-out), you can use ActionItem with ios.position="left".

Android Specifics

In Android, you cannot set text inside the navigation button. You can use the icon property to set an image (e.g., ~\images\nav-image.png or res:\\ic_nav). You can use android.systemIcon to set one of the system icons available in Android. In this case, there is no default behaviour for NavigationButton's tap event, and we should define manually the callback function, which will be executed.

Improve this document

Demo Source


Setting App Icon Android

You can set the application icon only for Android. By default, the application icon is hidden. You can show it by setting the android.iconVisibility property to always.

<Page.actionBar>
    <ActionBar title="App Icon Demo" android.icon="res://icon" android.iconVisibility="always"></ActionBar>
</Page.actionBar>

Improve this document

Demo Source


Styling

The ActionBar has some CSS styling limitations. You can use only background-color and color properties. Here is an example:

<Page.actionBar>
    <ActionBar title="ActionBar Style">
        <NavigationButton text="Go Back" android.systemIcon="ic_menu_back"></NavigationButton>
        <ActionItem ios.systemIcon="2" android.systemIcon="ic_menu_edit" ios.position="right"></ActionItem>
    </ActionBar>
</Page.actionBar>
ActionBar {
    background-color:  #3C5AFD;
    color: white;
}

In iOS, the color property affects the color of the title and the action items. In Android, the color property affects only the title text. However, you can set the default color of the text in the action items by adding an actionMenuTextColor item in the Android theme (inside App_Resources\Android\values\styles.xml).

Note: Setting other CSS properties (e.g., font-family) will only affect the views defined inside titleView.

Improve this document

Demo Source


API Reference for the ActionBar Class API Reference for the Known Colors

Native Component

Android iOS
android.widget.Toolbar UIView