Show navigation Hide navigation

Support Library

The Android Support Library offers a number of features that are not built into the framework. These libraries offer backward-compatible versions of new features, provide useful UI elements that are not included in the framework, and provide a range of utilities that apps can draw on.

Overview

In many cases, a feature may be valuable to many app developers, but not appropriate to include in the Android framework itself. For example, an app might only need a feature for specialized use cases, such as to smooth the transition between different versions of the Android system.

To address these situations, the Android SDK includes several libraries collectively called the Android Support Library. App developers can include any of these libraries if they want to incorporate the library functionality into their apps.

Support libraries provide a range of different features:

Backward Compatibility

Figure 1. Because this app uses support library UI elements its interface incorporates material design principles, even though it is running on Android 4.4, which does not include native support for material design.

Support libraries allow apps running on older versions of the Android platform to support features made available on newer versions of the platform. For example, an app running on a version of Android lower than 5.0 (API level 21) that relies on framework classes cannot display material-design elements, as that version of the Android framework doesn't support material design. However, if the app incorporates the Support Library's appcompat library, the app has access to many of the features available in API level 21, including support for material design. As a result, your app can deliver a more consistent experience across a broader range of platform versions.

In some cases, the support library version of a class depends as much as possible on the functionality that the framework provides. In these cases, if an app calls one of the support class's methods, the support library's behavior depends on what version of Android the app is running on. If the framework provides the necessary functionality, the support library calls on the framework to perform the task. If the app is running on an earlier version of Android, and the framework doesn't expose the needed functionality, the support library may try to provide the functionality itself, or may act as a no-op. In either case, the app generally doesn't need to check what version of Android it's running on; instead, the app can rely on the support library to do those checks and choose appropriate behavior. Generally, classes whose names end in …Compat (like ActivityCompat) behave this way.

In other cases, the support library class provides a complete, standalone version of a framework class that does not rely on the availability of any framework APIs. These methods provide consistent behavior across all supported platforms.

In either case, the app does not need to check the system version at run time. The app can rely on the support library class to do the appropriate system checks, and modify its behavior as necessary.

Support for General Layout Patterns

Support libraries provide user interface elements not offered by the Android framework. For example, the Android Support Library offers additional layout classes, like DrawerLayout. These classes follow recommended Android design practices; for example, the Design Library follows the principles of material design in a way that works across many versions of Android.

By using these support library classes, you can avoid having to reinvent the wheel; if your app has a particular user interface requirement, you can draw on existing code, which provides a user interface that users will already be familiar with. These elements also help you build an app that looks and feels like a part of the Android ecosystem. For example, many apps need to display arbitrarily long lists of elements, and need to be able to quickly and efficiently reuse those elements as the list changes; this might be a list of emails, contacts, music albums, and so on. Those apps can use the support library RecyclerView widget to display the list. This saves the app developer from having to develop the list from scratch, and also ensures that the user will see a list that looks and behaves like lists in other apps.

Support for Different Form Factors

The Android SDK provides libraries for a number of different form factors, such as TV and wearables. An app can depend on the appropriate support library to provide functionality across a wide range of platform versions, and can provide content on external screens, speakers, and other destination devices.

General Utilities

The Android Support Library provides backward-compatible utility functions. Apps can use these utility functions to provide an appropriate user experience across a wide range of Android system versions. For example, support library permission methods behave appropriately depending on what platform version your app is running on. If the platform supports the runtime permissions model, these methods request the appropriate permission from the user; on platform versions that do not support the runtime permissions model, the methods check whether the appropriate permission was granted at install time.

Support Library Revision History

This section provides details about the Support Library package releases.

Android Support Library, revision 23.3.0 (April 2016)

Changes for v4 Support Library:
  • Added AppLaunchChecker to help track how your app has been launched by the user in the past. hasStartedFromLauncher() lets you know if the user has launched your app from the home screen before, or if it has only been started by other means (for example, to view specific web URLs).
  • Fixed a memory leak in MediaBrowserServiceCompat.mConnections. (Issue 205220)
  • Fixed issue where ViewPager does not account for page margins when flipping page. (Issue 203816)
  • Fragment.onRequestPermissionsResult() is now delivered to child fragments.
Changes for v7 appcompat library:
Changes for v7 mediarouter library:
Changes for v7 Preference library:
Changes for v7 recyclerview library:
Changes for Design Support Library:

Android Support Library, revision 23.2.1 (March 2016)

Changes for v4 Support Library:
Changes for v7 appcompat library:
Changes for v7 cardview library:
Changes for v7 recyclerview library:
Changes for v7 mediarouter library:
Changes for v17 Leanback Library:
  • Fixed an issue with GridLayout.onAddFocusables() that caused the wrong item to be selected.
  • Fixed issue with GuidedStepFragment actions disappearing after an action was collapsed.
Changes for Design Support Library:
Changes for VectorDrawableCompat:
  • Fixed a bug where the wrong variable was read for android:tintMode. (Issue 201907)

Android Support Library, revision 23.2.0 (February 2016)

Changes for v4 Support library:
  • Added MediaBrowserCompat for MediaBrowser support, and MediaBrowserServiceCompat for MediaBrowserService support. This is useful when connecting a media app’s background service with UI components, and integrating with Android Auto and Android Wear without requiring API level 21 or higher.
  • The system now calls onActivityResult() for a nested FragmentActivity.
Changes for v7 AppCompat library:
  • Added Night Mode functionality to API level 14 and higher. Switch between Material Light and Material Dark Themes based on the time of day or app-specific setting.
    • Day and night themes can be found here: <sdk>/extras/android/support/v7/appcompat/res/values/themes_daynight.xml
    • AppCompatDelegate.setDefaultNightMode(): sets the app’s default mode by passing one of the following constants:
      • MODE_NIGHT_AUTO
      • MODE_NIGHT_NO
      • MODE_NIGHT_YES
      • MODE_NIGHT_FOLLOW_SYSTEM
    • AppCompatDelegate.setLocalNightMode(): overrides the night mode setting for the local app component.
    • AppCompatDelegate.getDefaultNightMode(): returns the default night mode.
Changes for v7 mediarouter library:
Changes for Design support library:
  • Added support for bottom sheets. An interaction plugin, BottomSheetBehavior, allows a child view of a CoordinatorLayout to act as a bottom sheet. The base class, BottomSheetCallback, provides callbacks to monitor bottom sheet events.
Changes for the CustomTabs support library:
  • Chrome Custom Tabs now allows apps to include a bottom bar with action buttons in addition to the existing top action button.
  • CustomTabsIntent.Builder.addToolBarItem(): adds an action button to a custom tab. You can use this to add multiple buttons.
  • CustomTabsSession.setToolBarItem(): updates the visuals for toolbar items. This method will only succeed if it is given a valid id and the browser session is in the foreground.
Added VectorDrawable support library:
  • Added Classes:
    • VectorDrawableCompat
    • AnimatedVectorDrawableCompat
  • Adds support for VectorDrawable assets to apps running on API level 7 or higher. AnimatedVectorDrawable assets are also supported on API level 11 or higher. Vector assets can be considerably smaller than image assets and should help reduce app size by reducing the amount of assets required to support multiple device screens.
  • This library is now a dependency of the v7 AppCompat library, allowing developers and AppCompat to easily use vector drawables. To use VectorDrawableCompat within an ImageButton or ImageView, use the app:srcCompat XML attribute or setImageResource() method.
  • To keep referencing attribute IDs on API level 20 or lower, add the following appt flag to your build,gradle file:
    • If you are building with Android Plugin for Gradle 1.5.0 or lower, add the following to your build.gradle file:
    • android {
        defaultConfig {
          // Stops the Gradle’s automatic rasterization of vectors
          generatedDensities = []
        }
         // Flag that tells aapt to keep the attribute ids
        aaptOptions {
          additionalParameters "--no-version-vectors"
        }
      }
      
    • If you are building with Android Plugin for Gradle 2.0.0 or higher, add the following to your build.gradle file:
    • android {
        defaultConfig {
          vectorDrawables.useSupportLibrary = true
        }
      }
      
Changes for v17 Leanback Library:
  • Added new capabilities to GuidedStepFragment, which is a component that guides users through a decision or series of decisions:
    • Added button actions to GuidedAction:
      • GuidedStepFragment.setButtonActions(): sets a list of GuidedAction buttons that the user may select from the Actions view.
    • Description fields are now editable:
      • GuidedAction.Builder.descriptionEditable(): when passing true, sets the action’s description to be editable.
      • GuidedAction.getEditDescription(): returns the editable description as a CharSequence.
    • Added drop-down lists of sub-actions:
      • GuidedAction.setSubActions(): sets a GuidedAction list as a drop-down menu of sub-actions.
  • Added the GuidedDatePickerAction widget for DatePicker functionality:
    • The date is selected using year, month, and day columns and has a customizable range.
    • GuidedDatePickerAction.Builder: builder class for the GuidedDatePickerAction object.
    • GuidedDatePickerAction.Builder.datePickerFormat(String datePickerFormat): set the desired date format by passing the appropriate three-character String, e.g. “YMD” or “MDY”. Alternatively, use the datePickerFormat XML attribute.
Changes for v7 RecyclerView library:

Android Support Library, revision 23.1.1 (November 2015)

Changes for v7 recyclerview library:
  • Fixed a crash that occurs when you perform a swipe-to-dismiss action that the ItemTouchHelper utility class provides, and then add an item. (Issue 190500)
Changes for v7 preference library:
Changes for v17 Leanback Support library:
  • Fixed a number of internal issues in this library.
Changes for Design Support library:
  • Added the getHeaderView method to the NavigationView class.
  • Fixed a transparent background issue for a FloatingActionButton object on devices running Android 4.0 (API level 15) and lower. (Issue 183315)

Android Support Library, revision 23.1.0 (October 2015)

Changes for v4 Support library:
  • Added OnScrollChangedListener interface support to the NestedScrollView widget. It allows you to receive callbacks when the scroll X or Y positions change.
  • Added a MediaButtonReceiver class to forward received playback controls to a service that’s managing the MediaSessionCompat class. The MediaSessionCompat class has a constructor that can automatically find a media button receiver in the manifest. A media button receiver is a key part to handling playback controls from hardware or bluetooth controls.
Changes for v7 appcompat library:
  • Added material design Seekbar and ImageButton widgets.
  • Updated the ImageView widget to support the tint feature.
  • Updated the look-and-feel of the SwitchCompat widget.
Changes for v7 mediarouter library:
  • Added the following features to the MediaRouteChooserDialog class:
    • Displays a loading page while discovering media route providers.
    • Includes a device type icon for easier device identification.
    • Sorts the routes according to frequency of use in the current app.
    • Supports landscape mode.
  • Added the following features to the MediaRouteControllerDialog class:
    • Recognizes screen casting and provides a proper description.
    • Supports various album art sizes and aspect ratios, and loads the art asynchronously.
    • Automatically selects the content color based on the primary color of the app.
    • Adjusts the dialog layout based on available screen space on the device.
    • Supports landscape mode.
Changes for v7 palette library:
  • Added the setRegion() method to support extracting color from a specific region of a Bitmap object.
Changes for v7 recyclerview library:
  • Added an improved animation API to the ItemAnimator class for better customizations:
    • Change animations no longer enforce two copies of the ViewHolder object, which enables item content animations. Also, the ItemAnimator object decides whether it wants to reuse the same ViewHolder object or create a new one.
    • The new information record API gives the ItemAnimator class the flexibility to collect data at the correct point in the layout lifecycle. This information is later passed into the animate callbacks.
  • Provided an easy transition plan for this backward-incompatible API change:
    • If you’ve previously extended the ItemAnimator class, you can change your base class to SimpleItemAnimator and your code should work as before. The SimpleItemAnimator class provides the old API by wrapping the new API.
    • Some methods were removed from the ItemAnimator class. The following code will no longer compile:
    • recyclerView.getItemAnimator().setSupportsChangeAnimations(false)

      You can replace it with:

      ItemAnimator animator = recyclerView.getItemAnimator();
      if (animator instanceof SimpleItemAnimator) {
         ((SimpleItemAnimator) animator).setSupportsChangeAnimations(false);
      }
                 
Changes for v7, v14, and v17 Preference Support library:
  • Removed APIs for controlling EditText dialogs.
Changes for v17 Leanback Support library:
  • Added a version of the GuidedStepFragment class for the Support library (extends android.support.v4.app.Fragment), and improved animations and transitions.
  • Updated the GuidedStepFragment class so it can be placed on top of existing content.
  • Added the ability to annotate different types of search completions to the SearchFragment class.
  • Added staggered slide transition support to the VerticalGridFragment class.
Changes for Design Support library:
  • Added character counting support to the TextInputLayout widget.
  • Added edge snapping support to the AppBarLayout class by adding the SCROLL_FLAG_SNAP constant. When scrolling ends, if the view is only partially visible, the view is snapped and scrolled to its closest edge.
  • Added support for custom views to the NavigationView class by using the app:actionLayout attribute or MenuItemCompat.setActionView() method.
Changes for Custom Tabs Support library:
  • Added the enableUrlBarHiding() method to the CustomTabsIntent class. It lets the client customize whether the URL bar should be hidden automatically on scroll down.
  • Added the setActionButton() method to the CustomTabsSession class. It lets the client change the icon for a custom action button in an already launched custom tab.
  • Added the TAB_SHOWN and TAB_HIDDEN constants as new events for the onNavigationEvent method of the CustomTabsCallback class.

Android Support Library, revision 23.0.1 (September 2015)

Changes for v7 and v14 Preference Support library:
  • Added the material design layout and style files. (Issue 183376)
Changes for v7 appcompat library:
  • Fixed crash issues for the Fragment class by limiting the use of hardware layers to Android 4.1 (API level 16) and higher. (Issue 183896)
  • Fixed an issue where hardware buttons did not work when an activity had set the Toolbar class to act as the ActionBar by using the setSupportActionBar() method. (Issue 183334)
  • Updated the AppCompatDialogFragment class so it no longer throws the Windows feature must be requested before adding content error. (Issue 183186)
Changes for Design Support library:
Changes for Custom Tabs Support library:

Android Support Library, revision 22.2.1 (July 2015)

Changes for Design Support library:

For a complete list of the Support Library changes, see the Support Library API Differences Report.

Android Support Library, revision 22.2.0 (May 2015)

Added Design Support library:
  • Added TextInputLayout for showing EditText hint and error text as floating labels.
  • Added FloatingActionButton for implementing a primary action on your interface as a floating action button, supporting either default or mini sizes.
  • Added Snackbar for providing lightweight feedback with an optional action in an animated snackbar.
  • Added TabLayout for implementing fixed and scrollable tabs as well as easy integration with ViewPager.
  • Added NavigationView for implementing navigation drawer contents, including the ability to inflate menu items via a Menu Resource.
  • Added CoordinatorLayout, a general purpose layout, used for building dependencies between sibling views and allowing easy scrolling reactions between components via CoordinatorLayout.Behavior. Many of the Design Library components rely on being a child of a CoordinatorLayout.
  • Added AppBarLayout, a container for a Toolbar and other views (such as TabLayout) for reacting to scrolling events by scrolling off the screen, becoming visible in reaction to a downward scroll, or collapsing/uncollapsing before scrolling off/onto the screen.
  • Added CollapsingToolbarLayout for controlling how a Toolbar collapses. A toolbar may collapse by: pinning components to the top of the screen while it collapses, introducing parallax scrolling of components such as an ImageView, or adding a content scrim color when the view is partially collapsed.
Changes for v4 support library:
Changes for v7 appcompat library:

For a complete list of the Support Library changes, see the Support Library API Differences Report.

Android Support Library, revision 22.1.0 (April 2015)

Changes for annotations library:
  • Added the Annotations library to provide support for enhanced code inspections. Annotations are added as metadata tags that you attach to variables, parameters, and return values to inspect method return values, passed parameters, and local variables and fields.
Changes for v4 support library:
Changes for v7 appcompat library:
Changes for v17 leanback library:
Changes for v7 recyclerview library:
Changes for v8 renderscript library:

Android Support Library, revision 22 (March 2015)

Changes for v4 support library:
Changes for v7 appcompat library:
Changes for v17 leanback library:
Changes for v7 mediarouter library:
Changes for v7 recyclerview library:

Android Support Library, revision 21.0.2 (November 2014)

Changes for v4 support library:
Changes for v7 appcompat library:
  • Added the PopupMenu constructor to support new popup menus.
  • Added support for a Collapse icon description in the Toolbar class.
  • Updated the SearchView widget to support displaying the commitIcon.
  • Removed the buttonGravity attribute from the Toolbar class.
Changes for v7 cardview library:
Changes for v7 recyclerview library:
Changes for v17 leanback library:
  • Added support to generate v4 code fragments.
  • Changed the secondary text color on CardView.

Android Support Library, revision 21.0.1 (November 2014)

Added multidex support library to support multiple Dalvik Executable (DEX) files for multi-dex file support prior to Android 5.0.

Android Support Library, revision 21 (October 2014)

Changes for v4 support library:
  • Added support for Fragment transitions for devices running Android 5.0 (API level 21). Be aware that transitions have no effect on devices running Android 4.4 and lower.
  • Added DocumentFile to ease the transition from File while working with document trees. However, this class demands more processing overhead compared to the platform's DocumentsContract API added in Android 4.4 (API level 19). So you should switch to using DocumentsContract when running on Android 4.4 and higher.
Changes for v7 appcompat library:
  • Added support for material design user interfaces.
  • Added Toolbar, which generalizes the functionality of ActionBar for use within app layouts.
  • Updated ActionBarDrawerToggle, which contains the menu-to-arrow animation
  • Updated common user interface widgets to allow tinting via theme attributes when running on pre-Android 5.0 devices
  • Added SwitchCompat, a backport of the Switch widget that was added in Android 4.0 (API level 14).
New v7 cardview library:
  • Added the CardView widget, which provides a material design-compatible implementation for displaying data items.
New v7 recyclerview library:
  • Added the RecyclerView widget, which provides a flexible list view for providing a limited window into a large data set.
New v7 palette library:
  • Added Palette class, which lets you extract prominent colors from an image.
New v17 leanback library:

Android Support Library, revision 20 (July 2014)

Changes for v4 support library:

Android Support Library, revision 19.1.0 (March 2014)

Changes for v4 support library:
  • Added the SwipeRefreshLayout class, which enables users to refresh the contents of a view with a vertical swipe gesture.
  • Fixed accessibility issues with navigation drawers.
Changes for v7 appcompat library:
  • Fixed background issues with the action bar.

Android Support Library, revision 19.0.1 (December 2013)

Changes for v4 support library:
Changes for v7 mediarouter library:
Changes for v8 renderscript library
  • Added error propagation for the RenderScript thunking layer.

Android Support Library, revision 19 (October 2013)

Changes for v4 support library:
Changes for v7 mediarouter library:
  • Added support for media playback queuing, setting HTTP header values and media playback duration.
  • Added explicit start, get, and end session actions for explicitly managing media playback sessions with media router.

Android Support Library, revision 18 (July 2013)

Changes for v4 support library:
New v7 appcompat library:
  • Added ActionBar to allow implementation of the action bar user interface design pattern back to Android 2.1 (API level 7) and higher. Use of this class requires that you implement your activity by extending the new ActionBarActivity class.
New v7 mediarouter library:

Added a new mediarouter library that provides support for the Google Cast developer preview. The v7 mediarouter library APIs provide a means of controlling the routing of media channels and streams from the current device to external screens, speakers, and other destination devices, with compatibility back to Android 2.1 (API level 7). See V7 mediarouter library for more information.

The v7 mediarouter library APIs introduced in Support Library r18 are subject to change in later revisions of the Support Library. At this time, we recommend using the library only in connection with the Google Cast developer preview.

Android Support Library, revision 13 (May 2013)

Changes for v4 support library:
New v7 gridlayout library:

Android Support Library, revision 12 (February 2013)

Changes for v4 support library:
  • Improved interaction behavior for ViewPager.
  • Fixed a bug that could cause ViewPager to select the wrong page.
  • Fixed use of removeView() method during layout for ViewPager.
  • Fixed issue with SearchViewCompat where using the back button to dismiss does not clear the search text. This fix only applies to host API levels 14 and higher.

Android Support Library, revision 11 (November 2012)

Changes for v4 support library:

Android Support Library, revision 10 (August 2012)

Changes for v4 support library:
  • Added support for notification features introduced in Android 4.1 (API level 16) with additions to NotificationCompat.

Android Support Library, revision 9 (June 2012)

Changes for v4 support library:

Android Support Library, revision 8 (April 2012)

Changes for v4 support library:
  • Fixed intent flags for PendingIntent objects generated by TaskStackBuilder.
  • Removed unused attributes from the gridlayout library projects to make sure the library can be built with API level 7 and higher.
  • Added .classpath and .project files for the gridlayout library project.

Android Support Library, revision 7 (March 2012)

Changes for v4 support library:
  • Added ShareCompat, which provides helper classes for sending and receiving content for social sharing applications, including new metadata for attributing shared data to the source app. This class also provides compatible integration with the new ShareActionProvider in Android 4.0.
  • Added NavUtils and TaskStackBuilder to provide support for implementing the Android Design guidelines for navigation. These additions include a way to implement the action bar's Up button across versions. For an example implementation of this pattern, see the AppNavigation sample in (<sdk>/samples/<platform>/AppNavigation).
  • Added NotificationCompat.Builder to provide a compatibility implementation of Android 3.0's Notification.Builder helper class for creating standardized system notifications.

Android Support Library, revision 6 (December 2011)

Note: Reference for support library APIs are now available with the framework references, for example: android.support.v4.app.

Changes for v4 support library:
  • Changes to ViewPager:
    • Added extra decorative view support for ViewPager. Decorative views may be supplied as child views of a pager in XML layout.
    • Added PagerAdapter.getPageTitle() to supply title strings for pages, which defaults to no title for each page.
    • Added PagerTitleStrip, a non-interactive title strip, that can be added as a child of ViewPager. Developers can supply text appearance and color, as well as layout sizing and gravity information.
    • Updated PagerAdapter methods to take ViewGroup objects, rather than View to avoid class casting in adapter implementations.
    • Updated ViewPager to use Launcher-style fling behavior.
    • Bug fixes for user interface interaction and test automation.
  • Support for Fragments:
  • Support for Accessiblity APIs:

Android Support Library, revision 5 (December 2011)

Changes for v4 support library:

Android Support Library, revision 4 (October 2011)

Changes for v4 support library:
  • Added EdgeEffectCompat to support EdgeEffect.
  • Added LocalBroadcastManager to allow applications to easily register for and receive intents within a single application without broadcasting them globally.
  • Added support in ViewCompat to check for and set overscroll modes for Views on Android 2.3 and later.
  • Changes to Fragment APIs:
    • Added new APIs to control the visibility of new menus.
    • Added custom animation APIs.
    • Added APIs in FragmentActivity to retain custom, non-configuration instance data.
    • Various bug fixes.
  • Fixed a Loader bug that caused issues in canceling AsyncTasks when running on Froyo and older versions of the platform. The support code now uses its own version of AsyncTask to keep the same behavior on all platform versions.

Android Support Library, revision 3 (July 2011)

Changes for v4 support library:
  • Adds support for Fragment.SavedState
  • Adds MotionEventCompat to support newer MotionEvent APIs
  • Adds VelocityTrackerCompat to support a newer VelocityTracker APIs
  • Adds ViewConfigurationCompat to support a newer ViewConfiguration APIs
  • All new APIs (available only in the support library) that allow you to create UIs with horizontal paging, allowing users to swipe left and right between content views. Classes to support this include:
    • ViewPager: A ViewGroup that manages the layout for the child views, which the user can swipe between.
    • PagerAdapter: An adapter that populates the ViewPager with the views that represent each page.
    • FragmentPagerAdapter: An extension of PagerAdapter for flipping between fragments.
    • FragmentStatePagerAdapter: An extension of PagerAdapter for flipping between fragments that uses the library's support for Fragment.SavedState.
New v13 support library:
  • Includes the FragmentPagerAdapter and FragmentStatePagerAdapter to support the horizontal paging.

    These are exactly the same as the APIs added to the v4 support library, but rely on other platform components in Android 3.2. Use this library instead of v4 if you're developing for Android 3.2 and higher (all other APIs in the v4 library are already available with API level 13).

Android Support Library, revision 2 (May 2011)

Changes for v4 library:

Android Support Library, revision 1 (March 2011)

Initial release with the v4 library.