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.

Usage

The ActionBar provides a title property and can be extended by using one or more ActionItem components and a single NavigationButton. The ActionBar also supports entirely custom views (see the Tips and Tricks section below).

<Page.actionBar>
    <ActionBar title="ActionBar Title" icon="">
        <NavigationButton icon="res://ic_arrow_back_black_24dp" tap="goBack" />
        <ActionBar.actionItems>
            <ActionItem icon="font://&#xf013;" class="fas" ios.position="right" tap="openSettings" />
        </ActionBar.actionItems>
    </ActionBar>
</Page.actionBar>

const frameModule = require("tns-core-modules/ui/frame");

function goBack() {
    frameModule.Frame.topmost().goBack();
}
function openSettings() {
    // implement the custom logic
}
exports.goBack = goBack;
exports.openSettings = openSettings;

import { Frame } from "tns-core-modules/ui/frame";

export function goBack() {
    Frame.topmost().goBack();
}
export function openSettings() {
    // implement the custom logic
}

ActionItem

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

<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>

• 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.

NavigationButton

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

iOS Specifics: The default text of the navigation button is the title of the previous page. In iOS, the back button is used explicitly for navigation. It navigates to the previous page and you can't 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". Values for ios.systemIcon are numbers from the UIBarButtonItem.SystemItem enumeration:

Android Specifics: In Android, you can't 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 tap event, and we should define manually the callback function, which will be executed. 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.

Styling

To style the ActionBar, you can use only background-color and color properties. Alternatively, you can use nativescript-theme-core 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.

<Page.actionBar>
    <ActionBar>
        <!-- Explicitly hiding the NavigaitonBar to prevent the default one on iOS-->
        <NavigationButton text="Back" visibility="collapsed" />

        <ActionBar.actionItems>
            <!-- 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 rows="*" columns="*" width="100"> -->
                        <Button row="0" col="0" text="Theme"  />
                    <!-- </GridLayout> -->
            </ActionItem>
        </ActionBar.actionItems>
    </ActionBar>
</Page.actionBar>

Note: 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).

Tips And Tricks

Setting App Icon For 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>

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.

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

<Page xmlns="http://www.nativescript.org/tns.xsd" navigatingTo="onNavigatingTo">
    <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>
</Page>

const fromObject = require("tns-core-modules/data/observable").fromObject;

function onNavigatingTo(args) {
    const page = args.object;
    page.bindingContext = fromObject({
        isEditing: false
    });
}
exports.onNavigatingTo = onNavigatingTo;

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);
}

Hide Show ActionBar

You can explicitly control the visibility of the ActionBar by setting the actionBarHidden property of the Pageor setting the Frame's actionBarVisibility property.

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

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>

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.

Creating ActionBar via 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();
    // for ios
    newNavigaitonButton.text = "Go Back";
    // for android
    newNavigaitonButton.android.systemIcon = "ic_menu_back";
    // or newNavigaitonButton.icon = "~\images\nav-image.png";
    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.

Properties

ActionBar Properties

ActionItem Properties

NavigationButton Properties

Events

API References

Native Component

See Also

Detailed documentation article about ActionBar functionalities.