material-components_material-components-android/docs/components/ProgressIndicator.md

Progress Indicator

Note: Due to an internal change of API, ProgressIndicator has been deprecated. It will be removed in the near future after the internal migration process.

com.google.android.material provides an implementation of linear and circular progress indicator, compatible back to API 15 (Ice Cream Sandwich MR1). The easiest way to make use of these indicators is through LinearProgressIndicator and CircularProgressIndicator.

LinearProgressIndicator

LinearProgressIndicator is a separate implementation of linear type. It can be added to the layout via xml or programmatically.

XML

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent">
  <!-- ... -->

  <com.google.android.material.progressindicator.LinearProgressIndicator
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/Progress"/>

  <!-- ... -->
</FrameLayout>

The default material style Widget.MaterialComponents.LinearProgressIndicator will be used as a determinate progress indicator. For the indeterminate mode, please add android:indeterminate="true" as the attribute.

Java

// An example to create a linear indeterminate progress indicator.
import com.google.android.material.progressindicator.LinearProgressIndicator;

LinearProgressIndicator indicator = new LinearProgressIndicator(getContext());

Default style

The default style Widget.MaterialComponents.LinearProgressIndicator will configure the indicator to draw a linear strip with the track thickness of 4dp. The indicator will swipe or grow from start to end regarding the layout direction. No animation will be used while showing or hiding.

Custom styling

LinearProgressIndicator can be configured with custom values to have different appearance.

Colors

The indicator color and track color can be configured by setting indicatorColor and trackColor. For multiple indicator color use, a color array can be assigned to indicatorColor, too. To set it programmatically, one can use setIndicatorColor(int[]).

Note: getIndicatorColor() will always return in the form of an int array regardless the number of indicator colors used.

Size and layout

LinearProgressIndicator can configure its height by adjusting trackThickness. trackThickness sets the width of the track/indicator; in the linear type case, it's the height of the strip.

Note: The width of strip depends on the view and its layout.

Showing and hiding with animations

The progress indicator can be animated in and out by calling #show() or #hide() actively on LinearProgressIndicator:

// ...
LinearProgressIndicator progress =
    (LinearProgressIndicator) findViewById(R.id.Progress);
progress.show();
// ... wait until finished
progress.hide();

The component can also be animated in when it's attached to the current window:

// ...
LinearLayout layout = (LinearLayout) findViewById(R.id.layout);
LinearProgressIndicator progress =
    new LinearProgressIndicator(getContext());
// ... configures the components.
layout.addView(progress, new LayoutParams(WRAP_CONTENT, WRAP_CONTENT));

By setting the showAnimationBehavior and hideAnimationBehavior, the indicator can have different animation effects as follows:

showAnimationBehavior
none	Appear immediately
upward	Expanding from the bottom edge
downward	Expanding from the top edge
hideAnimationBehavior
none	Disappear immediately
upward	Collapsing to the top edge
downward	Collapsing to the bottom edge

CircularProgressIndicator

CircularProgressIndicator is a separate implementation of circular type. It can be added to the layout via xml or programmatically.

XML

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent">
  <!-- ... -->

  <com.google.android.material.progressindicator.CircularProgressIndicator
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/Progress"/>

  <!-- ... -->
</FrameLayout>

The default material style Widget.MaterialComponents.CircularProgressIndicator will be used as a determinate progress indicator. For the indeterminate mode, please add android:indeterminate="true" as the attribute.

Java

// An example to create a circular indeterminate progress indicator.
import com.google.android.material.progressindicator.CircularProgressIndicator;

CircularProgressIndicator indicator = new CircularProgressIndicator(getContext());

Default style

The default style Widget.MaterialComponents.CircularProgressIndicator will configure the indicator to draw a circular (or partial) ring with the track thickness of 4dp. The indicator size is 40dp measured as the outer edge. There is also 4dp inset added on all sides. The indicator will spin or grow clockwise regardless the layout direction. No animation will be used while showing or hiding.

Custom styling

CircularProgressIndicator can be configured with custom values to have different appearance.

Colors

Same as LinearProgressIndicator.

Size and layout

CircularProgressIndicator can configure its size by adjusting trackThickness, indicatorSize, and indicatorInset. trackThickness sets the thickness of the track/indicator. indicatorSize sets the size of the ring by the diameter of the outer edge. indicatorInset gives an extra space between the outer edge to the drawable's bounds.

Note: If the trackThickness is greater than the half of the indicatorSize, IllegalArgumentException will be thrown during initialization.

Showing and hiding with animations

The progress indicator can be animated in and out by calling #show() or #hide() actively on CircularProgressIndicator:

// ...
CircularProgressIndicator progress =
    (CircularProgressIndicator) findViewById(R.id.Progress);
progress.show();
// ... wait until finished
progress.hide();

The component can also be animated in when it's attached to the current window:

// ...
LinearLayout layout = (LinearLayout) findViewById(R.id.layout);
CircularProgressIndicator progress =
    new CircularProgressIndicator(getContext());
// ... configures the components.
layout.addView(progress, new LayoutParams(WRAP_CONTENT, WRAP_CONTENT));

By setting the showAnimationBehavior and hideAnimationBehavior, the indicator can have different animation effects as follows:

showAnimationBehavior
none	Appear immediately
inward	Expanding from the outer edge
outward	Expanding from the inner edge
hideAnimationBehavior
none	Disappear immediately
inward	Collapsing to the inner edge
outward	Collapsing to the outer edge

Caveats

CircularProgressIndicator and LinearProgressIndicator are final. For more customized appearances, please consider to implement custom DrawingDelegate and IndetermianteAnimatorDelegate and inherit from the BaseProgressIndicator.