The action bar is a window feature that identifies the user location, and provides user actions and navigation modes. Using the action bar offers your users a familiar interface across applications that the system gracefully adapts for different screen configurations.

Figure 1. An action bar that includes the [1] app icon, [2] two action items, and [3] action overflow.

For more information about the action bar's interaction patterns and design guidelines, see the Action Bar design guide.

The {@link android.app.ActionBar} APIs were first added in Android 3.0 (API level 11) but they are also available in the Support Library for compatibility with Android 2.1 (API level 7) and above.

This guide focuses on how to use the support library's action bar, but if your app supports only Android 3.0 or higher, you should use the {@link android.app.ActionBar} APIs in the framework. Most of the APIs are the same—but reside in a different package namespace—with a few exceptions to method names or signatures that are noted in the sections below.

Note: If you're looking for information about the contextual action bar for displaying contextual action items, see the Menu guide.

Adding the Action Bar

As mentioned above, this guide focuses on how to use the {@link android.support.v7.app.ActionBar} APIs in the support library. So before you can add the action bar, you must set up your project with the appcompat v7 support library by following the instructions in the Support Library Setup.

Once your project is set up with the support library, here's how to add the action bar:

Now your activity includes the action bar when running on Android 2.1 (API level 7) or higher.

Removing the action bar

You can hide the action bar at runtime by calling {@link android.support.v7.app.ActionBar#hide}. For example:

When the action bar hides, the system adjusts your layout to fill the screen space now available. You can bring the action bar back by calling {@link android.support.v7.app.ActionBar#show()}.

Beware that hiding and removing the action bar causes your activity to re-layout in order to account for the space consumed by the action bar. If your activity often hides and shows the action bar, you might want to enable overlay mode. Overlay mode draws the action bar in front of your activity layout, obscuring the top portion. This way, your layout remains fixed when the action bar hides and re-appears. To enable overlay mode, create a custom theme for your activity and set {@link android.support.v7.appcompat.R.attr#windowActionBarOverlay windowActionBarOverlay} to {@code true}. For more information, see the section below about Styling the Action Bar.

Using a logo instead of an icon

By default, the system uses your application icon in the action bar, as specified by the {@code icon} attribute in the {@code <application>} or {@code <activity>} element. However, if you also specify the {@code logo} attribute, then the action bar uses the logo image instead of the icon.

A logo should usually be wider than the icon, but should not include unnecessary text. You should generally use a logo only when it represents your brand in a traditional format that users recognize. A good example is the YouTube app's logo—the logo represents the expected user brand, whereas the app's icon is a modified version that conforms to the square requirement for the launcher icon.

Adding Action Items

The action bar provides users access to the most important action items relating to the app's current context. Those that appear directly in the action bar with an icon and/or text are known as action buttons. Actions that can't fit in the action bar or aren't important enough are hidden in the action overflow. The user can reveal a list of the other actions by pressing the overflow button on the right side (or the device Menu button, if available).

When your activity starts, the system populates the action items by calling your activity's {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method. Use this method to inflate a menu resource that defines all the action items. For example, here's a menu resource defining a couple of menu items:

Then in your activity's {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method, inflate the menu resource into the given {@link android.view.Menu} to add each item to the action bar:

To request that an item appear directly in the action bar as an action button, include {@code showAsAction="ifRoom"} in the {@code <item>} tag. For example:

If there's not enough room for the item in the action bar, it will appear in the action overflow.

If your menu item supplies both a title and an icon—with the {@code title} and {@code icon} attributes—then the action item shows only the icon by default. If you want to display the text title, add {@code "withText"} to the {@code showAsAction} attribute. For example:

Note: The {@code "withText"} value is a hint to the action bar that the text title should appear. The action bar will show the title when possible, but might not if an icon is available and the action bar is constrained for space.

You should always define the {@code title} for each item even if you don't declare that the title appear with the action item, for the following reasons:

The {@code icon} is optional, but recommended. For icon design recommendations, see the Iconography design guide. You can also download a set of standard action bar icons (such as for Search or Discard) from the Downloads page.

You can also use {@code "always"} to declare that an item always appear as an action button. However, you should not force an item to appear in the action bar this way. Doing so can create layout problems on devices with a narrow screen. It's best to instead use {@code "ifRoom"} to request that an item appear in the action bar, but allow the system to move it into the overflow when there's not enough room. However, it might be necessary to use this value if the item includes an action view that cannot be collapsed and must always be visible to provide access to a critical feature.

Handling clicks on action items

When the user presses an action, the system calls your activity's {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method. Using the {@link android.view.MenuItem} passed to this method, you can identify the action by calling {@link android.view.MenuItem#getItemId()}. This returns the unique ID provided by the {@code <item>} tag's {@code id} attribute so you can perform the appropriate action. For example:

Note: If you inflate menu items from a fragment, via the {@link android.app.Fragment} class's {@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu()} callback, the system calls {@link android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} for that fragment when the user selects one of those items. However, the activity gets a chance to handle the event first, so the system first calls {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} on the activity, before calling the same callback for the fragment. To ensure that any fragments in the activity also have a chance to handle the callback, always pass the call to the superclass as the default behavior instead of returning {@code false} when you do not handle the item.

Using split action bar

Split action bar provides a separate bar at the bottom of the screen to display all action items when the activity is running on a narrow screen (such as a portrait-oriented handset).

Separating the action items this way ensures that a reasonable amount of space is available to display all your action items on a narrow screen, while leaving room for navigation and title elements at the top.

To enable split action bar when using the support library, you must do two things:

Using split action bar also allows navigation tabs to collapse into the main action bar if you remove the icon and title (as shown on the right in figure 3). To create this effect, disable the action bar icon and title with {@link android.support.v7.app.ActionBar#setDisplayShowHomeEnabled setDisplayShowHomeEnabled(false)} and {@link android.support.v7.app.ActionBar#setDisplayShowTitleEnabled setDisplayShowTitleEnabled(false)}.

Navigating Up with the App Icon

Enabling the app icon as an Up button allows the user to navigate your app based on the hierarchical relationships between screens. For instance, if screen A displays a list of items, and selecting an item leads to screen B, then screen B should include the Up button, which returns to screen A.

Note: Up navigation is distinct from the back navigation provided by the system Back button. The Back button is used to navigate in reverse chronological order through the history of screens the user has recently worked with. It is generally based on the temporal relationships between screens, rather than the app's hierarchy structure (which is the basis for up navigation).

To enable the app icon as an Up button, call {@link android.support.v7.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled()}. For example:

Now the icon in the action bar appears with the Up caret (as shown in figure 4). However, it won't do anything by default. To specify the activity to open when the user presses Up button, you have two options:

Note: If you've built your app hierarchy using a series of fragments instead of multiple activities, then neither of the above options will work. Instead, to navigate up through your fragments, override {@link android.support.v7.app.ActionBarActivity#onSupportNavigateUp()} to perform the appropriate fragment transaction—usually by popping the current fragment from the back stack by calling {@link android.support.v4.app.FragmentManager#popBackStack()}.

Adding an Action View

An action view is a widget that appears in the action bar as a substitute for an action button. An action view provides fast access to rich actions without changing activities or fragments, and without replacing the action bar. For example, if you have an action for Search, you can add an action view to embeds a {@link android.support.v7.widget.SearchView} widget in the action bar, as shown in figure 5.

To declare an action view, use either the {@code actionLayout} or {@code actionViewClass} attribute to specify either a layout resource or widget class to use, respectively. For example, here's how to add the {@link android.support.v7.widget.SearchView} widget:

Notice that the {@code showAsAction} attribute also includes the {@code "collapseActionView"} value. This is optional and declares that the action view should be collapsed into a button. (This behavior is explained further in the following section about Handling collapsible action views.)

If you need to configure the action view (such as to add event listeners), you can do so during the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback. You can acquire the action view object by calling the static method {@link android.support.v4.view.MenuItemCompat#getActionView MenuItemCompat.getActionView()} and passing it the corresponding {@link android.view.MenuItem}. For example, the search widget from the above sample is acquired like this:

Handling collapsible action views

To preserve the action bar space, you can collapse your action view into an action button. When collapsed, the system might place the action into the action overflow, but the action view still appears in the action bar when the user selects it. You can make your action view collapsible by adding {@code "collapseActionView"} to the {@code showAsAction} attribute, as shown in the XML above.

Because the system expands the action view when the user selects the action, you do not need to respond to the item in the {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} callback. The system still calls {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()}, but if you return {@code true} (indicating you've handled the event instead), then the action view will not expand.

The system also collapses your action view when the user presses the Up button or Back button.

If you need to update your activity based on the visibility of your action view, you can receive callbacks when the action is expanded and collapsed by defining an {@link android.support.v4.view.MenuItemCompat.OnActionExpandListener OnActionExpandListener} and passing it to {@link android.support.v4.view.MenuItemCompat#setOnActionExpandListener setOnActionExpandListener()}. For example:

Adding an Action Provider

Similar to an action view, an action provider replaces an action button with a customized layout. However, unlike an action view, an action provider takes control of all the action's behaviors and an action provider can display a submenu when pressed.

To declare an action provider, supply the {@code actionViewClass} attribute in the menu {@code <item>} tag with a fully-qualified class name for an {@link android.support.v4.view.ActionProvider}.

You can build your own action provider by extending the {@link android.support.v4.view.ActionProvider} class, but Android provides some pre-built action providers such as {@link android.support.v7.widget.ShareActionProvider}, which facilitates a "share" action by showing a list of possible apps for sharing directly in the action bar (as shown in figure 6).

Because each {@link android.support.v4.view.ActionProvider} class defines its own action behaviors, you don't need to listen for the action in the {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method. If necessary though, you can still listen for the click event in the {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method in case you need to simultaneously perform another action. But be sure to return {@code false} so that the the action provider still receives the {@link android.support.v4.view.ActionProvider#onPerformDefaultAction()} callback to perform its intended action.

However, if the action provider provides a submenu of actions, then your activity does not receive a call to {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} when the user opens the list or selects one of the submenu items.

Using the ShareActionProvider

To add a "share" action with {@link android.support.v7.widget.ShareActionProvider}, define the {@code actionProviderClass} for an {@code <item>} tag with the {@link android.support.v7.widget.ShareActionProvider} class. For example:

Now the action provider takes control of the action item and handles both its appearance and behavior. But you must still provide a title for the item to be used when it appears in the action overflow.

The only thing left to do is define the {@link android.content.Intent} you want to use for sharing. To do so, edit your {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method to call {@link android.support.v4.view.MenuItemCompat#getActionProvider MenuItemCompat.getActionProvider()} and pass it the {@link android.view.MenuItem} holding the action provider. Then call {@link android.support.v7.widget.ShareActionProvider#setShareIntent setShareIntent()} on the returned {@link android.support.v7.widget.ShareActionProvider} and pass it an {@link android.content.Intent#ACTION_SEND} intent with the appropriate content attached.

You should call {@link android.support.v7.widget.ShareActionProvider#setShareIntent setShareIntent()} once during {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} to initialize the share action, but because the user context might change, you must update the intent any time the shareable content changes by again calling {@link android.support.v7.widget.ShareActionProvider#setShareIntent setShareIntent()}.

The {@link android.support.v7.widget.ShareActionProvider} now handles all user interaction with the item and you do not need to handle click events from the {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} callback method.

By default, the {@link android.support.v7.widget.ShareActionProvider} retains a ranking for each share target based on how often the user selects each one. The share targets used more frequently appear at the top of the drop-down list and the target used most often appears directly in the action bar as the default share target. By default, the ranking information is saved in a private file with a name specified by {@link android.support.v7.widget.ShareActionProvider#DEFAULT_SHARE_HISTORY_FILE_NAME}. If you use the {@link android.support.v7.widget.ShareActionProvider} or an extension of it for only one type of action, then you should continue to use this default history file and there's nothing you need to do. However, if you use {@link android.support.v7.widget.ShareActionProvider} or an extension of it for multiple actions with semantically different meanings, then each {@link android.support.v7.widget.ShareActionProvider} should specify its own history file in order to maintain its own history. To specify a different history file for the {@link android.support.v7.widget.ShareActionProvider}, call {@link android.support.v7.widget.ShareActionProvider#setShareHistoryFileName setShareHistoryFileName()} and provide an XML file name (for example, {@code "custom_share_history.xml"}).

Note: Although the {@link android.support.v7.widget.ShareActionProvider} ranks share targets based on frequency of use, the behavior is extensible and extensions of {@link android.support.v7.widget.ShareActionProvider} can perform different behaviors and ranking based on the history file (if appropriate).

Creating a custom action provider

Creating your own action provider allows you to re-use and manage dynamic action item behaviors in a self-contained module, rather than handle action item transformations and behaviors in your fragment or activity code. As shown in the previous section, Android already provides an implementation of {@link android.support.v4.view.ActionProvider} for share actions: the {@link android.support.v7.widget.ShareActionProvider}.

To create your own action provider for a different action, simply extend the {@link android.support.v4.view.ActionProvider} class and implement its callback methods as appropriate. Most importantly, you should implement the following:

Adding Navigation Tabs

Tabs in the action bar make it easy for users to explore and switch between different views in your app. The tabs provided by the {@link android.support.v7.app.ActionBar} are ideal because they adapt to different screen sizes. For example, when the screen is wide enough the tabs appear in the action bar alongside the action buttons (such as when on a tablet, shown in figure 7), while when on a narrow screen they appear in a separate bar (known as the "stacked action bar", shown in figure 8). In some cases, the Android system will instead show your tab items as a drop-down list to ensure the best fit in the action bar.

To get started, your layout must include a {@link android.view.ViewGroup} in which you place each {@link android.app.Fragment} associated with a tab. Be sure the {@link android.view.ViewGroup} has a resource ID so you can reference it from your code and swap the tabs within it. Alternatively, if the tab content will fill the activity layout, then your activity doesn't need a layout at all (you don't even need to call {@link android.app.Activity#setContentView setContentView()}). Instead, you can place each fragment in the default root view, which you can refer to with the {@code android.R.id.content} ID.

Once you determine where the fragments appear in the layout, the basic procedure to add tabs is:

Notice that the {@link android.support.v7.app.ActionBar.TabListener} callback methods don't specify which fragment is associated with the tab, but merely which {@link android.support.v7.app.ActionBar.Tab} was selected. You must define your own association between each {@link android.app.ActionBar.Tab} and the appropriate {@link android.app.Fragment} that it represents. There are several ways you can define the association, depending on your design.

For example, here's how you might implement the {@link android.app.ActionBar.TabListener} such that each tab uses its own instance of the listener:

Caution: You must not call {@link android.app.FragmentTransaction#commit} for the fragment transaction in each of these callbacks—the system calls it for you and it may throw an exception if you call it yourself. You also cannot add these fragment transactions to the back stack.

In this example, the listener simply attaches ({@link android.app.FragmentTransaction#attach attach()}) a fragment to the activity layout—or if not instantiated, creates the fragment and adds ({@link android.app.FragmentTransaction#add add()}) it to the layout (as a child of the {@code android.R.id.content} view group)—when the respective tab is selected, and detaches ({@link android.app.FragmentTransaction#detach detach()}) it when the tab is unselected.

All that remains is to create each {@link android.app.ActionBar.Tab} and add it to the {@link android.app.ActionBar}. Additionally, you must call {@link android.app.ActionBar#setNavigationMode(int) setNavigationMode(NAVIGATION_MODE_TABS)} to make the tabs visible.

If your activity stops, you should retain the currently selected tab with the saved instance state so you can open the appropriate tab when the user returns. When it's time to save the state, you can query the currently selected tab with {@link android.support.v7.app.ActionBar#getSelectedNavigationIndex()}. This returns the index position of the selected tab.

Caution: It's important that you save the state of each fragment so when users switch fragments with the tabs and then return to a previous fragment, it looks the way it did when they left. Some of the state is saved by default, but you may need to manually save state for customized views. For information about saving the state of your fragment, see the Fragments API guide.

Note: The above implementation for {@link android.support.v7.app.ActionBar.TabListener} is one of several possible techniques. Another popular option is to use {@link android.support.v4.view.ViewPager} to manage the fragments so users can also use a swipe gesture to switch tabs. In this case, you simply tell the {@link android.support.v4.view.ViewPager} the current tab position in the {@link android.support.v7.app.ActionBar.TabListener#onTabSelected onTabSelected()} callback. For more information, read Creating Swipe Views with Tabs.

Adding Drop-down Navigation

As another mode of navigation (or filtering) for your activity, the action bar offers a built in drop-down list (also known as a "spinner"). For example, the drop-down list can offer different modes by which content in the activity is sorted.

Using the drop-down list is useful when changing the content is important but not necessarily a frequent occurrence. In cases where switching the content is more frequent, you should use navigation tabs instead.

This procedure is relatively short, but implementing the {@link android.widget.SpinnerAdapter} and {@link android.app.ActionBar.OnNavigationListener} is where most of the work is done. There are many ways you can implement these to define the functionality for your drop-down navigation and implementing various types of {@link android.widget.SpinnerAdapter} is beyond the scope of this document (you should refer to the {@link android.widget.SpinnerAdapter} class reference for more information). However, below is an example for a {@link android.widget.SpinnerAdapter} and {@link android.app.ActionBar.OnNavigationListener} to get you started (click the title to reveal the sample).

Example SpinnerAdapter and OnNavigationListener

{@link android.widget.SpinnerAdapter} is an adapter that provides data for a spinner widget, such as the drop-down list in the action bar. {@link android.widget.SpinnerAdapter} is an interface that you can implement, but Android includes some useful implementations that you can extend, such as {@link android.widget.ArrayAdapter} and {@link android.widget.SimpleCursorAdapter}. For example, here's an easy way to create a {@link android.widget.SpinnerAdapter} by using {@link android.widget.ArrayAdapter} implementation, which uses a string array as the data source:

SpinnerAdapter mSpinnerAdapter = ArrayAdapter.createFromResource(this, R.array.action_list,
          android.R.layout.simple_spinner_dropdown_item);

The {@link android.widget.ArrayAdapter#createFromResource createFromResource()} method takes three parameters: the application {@link android.content.Context}, the resource ID for the string array, and the layout to use for each list item.

A string array defined in a resource looks like this:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array name="action_list">
        <item>Mercury</item>
        <item>Venus</item>
        <item>Earth</item>
    </string-array>
</pre>

The {@link android.widget.ArrayAdapter} returned by {@link android.widget.ArrayAdapter#createFromResource createFromResource()} is complete and ready for you to pass it to {@link android.app.ActionBar#setListNavigationCallbacks setListNavigationCallbacks()} (in step 4 from above). Before you do, though, you need to create the {@link android.app.ActionBar.OnNavigationListener OnNavigationListener}.

Your implementation of {@link android.app.ActionBar.OnNavigationListener} is where you handle fragment changes or other modifications to your activity when the user selects an item from the drop-down list. There's only one callback method to implement in the listener: {@link android.app.ActionBar.OnNavigationListener#onNavigationItemSelected onNavigationItemSelected()}.

The {@link android.app.ActionBar.OnNavigationListener#onNavigationItemSelected onNavigationItemSelected()} method receives the position of the item in the list and a unique item ID provided by the {@link android.widget.SpinnerAdapter}.

Here's an example that instantiates an anonymous implementation of {@link android.app.ActionBar.OnNavigationListener OnNavigationListener}, which inserts a {@link android.app.Fragment} into the layout container identified by {@code R.id.fragment_container}:

mOnNavigationListener = new OnNavigationListener() {
  // Get the same strings provided for the drop-down's ArrayAdapter
  String[] strings = getResources().getStringArray(R.array.action_list);

  @Override
  public boolean onNavigationItemSelected(int position, long itemId) {
    // Create new fragment from our own Fragment class
    ListContentFragment newFragment = new ListContentFragment();
    FragmentTransaction ft = openFragmentTransaction();
    // Replace whatever is in the fragment container with this fragment
    //  and give the fragment a tag name equal to the string at the position selected
    ft.replace(R.id.fragment_container, newFragment, strings[position]);
    // Apply changes
    ft.commit();
    return true;
  }
};

This instance of {@link android.app.ActionBar.OnNavigationListener OnNavigationListener} is complete and you can now call {@link android.app.ActionBar#setListNavigationCallbacks setListNavigationCallbacks()} (in step 4), passing the {@link android.widget.ArrayAdapter} and this {@link android.app.ActionBar.OnNavigationListener OnNavigationListener}.

In this example, when the user selects an item from the drop-down list, a fragment is added to the layout (replacing the current fragment in the {@code R.id.fragment_container} view). The fragment added is given a tag that uniquely identifies it, which is the same string used to identify the fragment in the drop-down list.

Here's a look at the {@code ListContentFragment} class that defines each fragment in this example:

public class ListContentFragment extends Fragment {
    private String mText;

    @Override
    public void onAttach(Activity activity) {
      // This is the first callback received; here we can set the text for
      // the fragment as defined by the tag specified during the fragment transaction
      super.onAttach(activity);
      mText = getTag();
    }

    @Override
    public View onCreateView(LayoutInflater inflater, ViewGroup container,
            Bundle savedInstanceState) {
        // This is called to define the layout for the fragment;
        // we just create a TextView and set its text to be the fragment tag
        TextView text = new TextView(getActivity());
        text.setText(mText);
        return text;
    }
}

Styling the Action Bar

If you want to implement a visual design that represents your app's brand, the action bar allows you to customize each detail of its appearance, including the action bar color, text colors, button styles, and more. To do so, you need to use Android's style and theme framework to restyle the action bar using special style properties.

Caution: For all background drawables you provide, be sure to use Nine-Patch drawables to allow stretching. The nine-patch image should be smaller than 40dp tall and 30dp wide.

General appearance

Action items

Navigation tabs

Drop-down lists

Example theme

Here's an example that defines a custom theme for an activity, {@code CustomActivityTheme}, that includes several styles to customize the action bar.

Notice that there are two version for each action bar style property. The first one includes the {@code android:} prefix on the property name to support API levels 11 and higher that include these properties in the framework. The second version does not include the {@code android:} prefix and is for older versions of the platform, on which the system uses the style property from the support library. The effect for each is the same.

Caution: Be certain that each theme and style declares a parent theme in the {@code <style>} tag, from which it inherits all styles not explicitly declared by your theme. When modifying the action bar, using a parent theme is important so that you can simply override the action bar styles you want to change without re-implementing the styles you want to leave alone (such as text size or padding in action items).

For more information about using style and theme resources in your application, read Styles and Themes.

Design Guide

In this document

Key classes

Adding the Action Bar

Removing the action bar

Using a logo instead of an icon

Adding Action Items

Handling clicks on action items

Using split action bar

Navigating Up with the App Icon

Design Guide

Adding an Action View

Handling collapsible action views

Adding an Action Provider

Using the ShareActionProvider

Creating a custom action provider

Adding Navigation Tabs

Design Guide

Also read

Example SpinnerAdapter and OnNavigationListener

Styling the Action Bar

General appearance

Action items

Navigation tabs

Drop-down lists

Example theme