# android-material-stepper
**Repository Path**: Hancher/android-material-stepper
## Basic Information
- **Project Name**: android-material-stepper
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-11
- **Last Updated**: 2025-12-11
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Android Material Stepper [](https://circleci.com/gh/stepstone-tech/android-material-stepper) [](https://codecov.io/gh/stepstone-tech/android-material-stepper) [](https://android-arsenal.com/details/1/5138) [](http://androidweekly.net/issues/issue-243)
This library allows to use Material steppers inside Android applications.
Quoting the [documentation](https://www.google.com/design/spec/components/steppers.html):
>Steppers display progress through a sequence by breaking it up into multiple logical and numbered steps.
All of the code & features mentioned in [Getting started](#getting-started) and [Advanced usage](#advanced-usage) are showcased in the sample app.
Moreover, you can find there other examples, e.g. how to persist state on rotation, display errors, change whether the user can go to the next step, etc. So please have a look!
## Jump to section
- [Supported steppers](#supported-steppers)
- [Supported features](#supported-features)
- [Getting started](#getting-started)
- [Advanced usage](#advanced-usage)
- [Making extra operations before going to the next step](#making-extra-operations-before-going-to-the-next-step)
- [Changing button labels & compound drawables per step](#changing-button-labels--compound-drawables-per-step)
- [Subtitles in tabs](#subtitles-in-tabs)
- [Custom styling](#custom-styling)
- [Using same stepper styling across the application](#using-same-stepper-styling-across-the-application)
- [Showing a Back button on first step](#showing-a-back-button-on-first-step)
- [Using Views instead of Fragments as Steps](#using-views-instead-of-fragments-as-steps)
- [Showing an error on tabs if step verification failed](#showing-an-error-on-tabs-if-step-verification-failed)
- [Stepper feedback](#stepper-feedback)
- [Changing button text color when going to the next step should be disabled](#changing-button-text-color-when-going-to-the-next-step-should-be-disabled)
- [Hiding bottom navigation bar](#hiding-bottom-navigation-bar)
- [StepperLayout attributes](#stepperlayout-attributes)
- [View attributes](#view-attributes)
- [StepperLayout style attributes](#stepperlayout-style-attributes)
- [Changelog](#changelog)
- [Espresso tests](#espresso-tests)
- [Contributing](#contributing)
- [License](#license)
## Supported steppers
### Mobile stepper with dots
### Mobile stepper with progress bar
### Mobile stepper without a progress indicator
### Horizontal stepper
## Supported features
- color customisation of individual widgets inside of the stepper via View attributes or a style from a theme
- custom texts of individual widgets inside of the stepper via View attributes or a style from a theme
- embedding the stepper anywhere in the view hierarchy and changing the stepper type for various device configurations, e.g. phone/tablet, portrait/landscape
- step validation
- use with Fragments or Views
- showing errors in tabs
- showing stepper feedback for ongoing operations (see [Stepper feedback](https://material.io/guidelines/components/steppers.html#steppers-types-of-steppers))
## Getting started
### Download (from JCenter)
```groovy
compile 'com.stepstone.stepper:material-stepper:4.3.1'
```
*Note:* This library adds a transitive dependency to AppCompat `25.4.0`
which is the minimum Android Support library version compatible with the Stepper library.
### Create layout in XML
```xml
```
For a complete list of StepperLayout attributes see [StepperLayout attributes](#StepperLayout attributes).
### Create step Fragment(s)
Step fragments must extend [android.support.v4.app.Fragment](http://developer.android.com/reference/android/support/v4/app/Fragment.html)
and implement `com.stepstone.stepper.Step`
```java
public class StepFragmentSample extends Fragment implements Step {
@Override
public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {
View v = inflater.inflate(R.layout.step, container, false);
//initialize your UI
return v;
}
@Override
public VerificationError verifyStep() {
//return null if the user can go to the next step, create a new VerificationError instance otherwise
return null;
}
@Override
public void onSelected() {
//update UI when selected
}
@Override
public void onError(@NonNull VerificationError error) {
//handle error inside of the fragment, e.g. show error on EditText
}
}
```
### Extend AbstractFragmentStepAdapter
AbstractFragmentStepAdapter extends [FragmentPagerAdapter](http://developer.android.com/reference/android/support/v4/app/FragmentPagerAdapter.html)
but instead of overriding the method `getItem(int)` you must override the `createStep(int)` method.
```java
public static class MyStepperAdapter extends AbstractFragmentStepAdapter {
public MyStepperAdapter(FragmentManager fm, Context context) {
super(fm, context);
}
@Override
public Step createStep(int position) {
final StepFragmentSample step = new StepFragmentSample();
Bundle b = new Bundle();
b.putInt(CURRENT_STEP_POSITION_KEY, position);
step.setArguments(b);
return step;
}
@Override
public int getCount() {
return 3;
}
@NonNull
@Override
public StepViewModel getViewModel(@IntRange(from = 0) int position) {
//Override this method to set Step title for the Tabs, not necessary for other stepper types
return new StepViewModel.Builder(context)
.setTitle(R.string.tab_title) //can be a CharSequence instead
.create();
}
}
```
### Set adapter in Activity
```java
public class StepperActivity extends AppCompatActivity {
private StepperLayout mStepperLayout;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
mStepperLayout = (StepperLayout) findViewById(R.id.stepperLayout);
mStepperLayout.setAdapter(new MyStepperAdapter(getSupportFragmentManager(), this));
}
}
```
### Add a StepperListener in the Activity (optional)
```java
public class StepperActivity extends AppCompatActivity implements StepperLayout.StepperListener {
@Override
protected void onCreate(Bundle savedInstanceState) {
//...
mStepperLayout.setListener(this);
}
@Override
public void onCompleted(View completeButton) {
Toast.makeText(this, "onCompleted!", Toast.LENGTH_SHORT).show();
}
@Override
public void onError(VerificationError verificationError) {
Toast.makeText(this, "onError! -> " + verificationError.getErrorMessage(), Toast.LENGTH_SHORT).show();
}
@Override
public void onStepSelected(int newStepPosition) {
Toast.makeText(this, "onStepSelected! -> " + newStepPosition, Toast.LENGTH_SHORT).show();
}
@Override
public void onReturn() {
finish();
}
}
```
## Advanced usage
### Making extra operations before going to the next step
After clicking on the Next button if the user wants to e.g.:
* save something in the database
* make a network call on a separate Thread
* simply save the data from the current step to some other component or parent Activity (see 'Passing data between steps' in the sample app for more details)
he can perform these operations and then invoke the `goToNextStep()` method of the `StepperLayout.OnNextClickedCallback` in the current Step.
If the user wants to perform these operations on the final step, when clicking on the Complete button, he needs to invoke the `complete()` method of the `StepperLayout.OnCompleteClickedCallback`.
While operations are performed, and the user would like to go back you can cancel them and then invoke `onBackClicked()` method of the `StepperLayout.OnBackClickedCallback`.
To do so the fragment/view must implement `BlockingStep` instead of `Step`.
Also, make sure that `goToNextStep()` and/or `complete()` get called on the main thread.
**Note:** `onNextClicked(StepperLayout.OnNextClickedCallback)` and ``onCompleteClicked(StepperLayout.OnCompleteClickedCallback)`` methods get invoked after step verification.
E.g.:
```java
public class DelayedTransitionStepFragmentSample extends Fragment implements BlockingStep {
//...
@Override
@UiThread
public void onNextClicked(final StepperLayout.OnNextClickedCallback callback) {
new Handler().postDelayed(new Runnable() {
@Override
public void run() {
callback.goToNextStep();
}
}, 2000L);
}
@Override
@UiThread
public void onCompleteClicked(final StepperLayout.OnCompleteClickedCallback callback) {
new Handler().postDelayed(new Runnable() {
@Override
public void run() {
callback.complete();
}
}, 2000L);
}
@Override
@UiThread
public void onBackClicked(StepperLayout.OnBackClickedCallback callback) {
Toast.makeText(this.getContext(), "Your custom back action. Here you should cancel currently running operations", Toast.LENGTH_SHORT).show();
callback.goToPrevStep();
}
}
```
### Changing button labels & compound drawables per step
Sometimes you might want to have different labels on the Next/Complete and/or Back navigation buttons on different steps e.g. use the default labels on the first few steps,
but display 'Summary' just before the last page.
You might also want to use your custom icons instead of the default navigation button compound drawables or not show the compound drawables for some of the buttons.
In such case you need to override the `getViewModel(int)` method from the `StepAdapter` e.g.
```java
@NonNull
@Override
public StepViewModel getViewModel(@IntRange(from = 0) int position) {
StepViewModel.Builder builder = new StepViewModel.Builder(context)
.setTitle(R.string.tab_title);
switch (position) {
case 0:
builder
.setEndButtonLabel("This way")
.setBackButtonLabel("Cancel")
.setNextButtonEndDrawableResId(R.drawable.ms_forward_arrow)
.setBackButtonStartDrawableResId(StepViewModel.NULL_DRAWABLE);
break;
case 1:
builder
.setEndButtonLabel(R.string.go_to_summary)
.setBackButtonLabel("Go to first")
.setBackButtonStartDrawableResId(R.drawable.ms_back_arrow);
break;
case 2:
builder
.setBackButtonLabel("Go back")
.setEndButtonLabel("I'm done!");
break;
default:
throw new IllegalArgumentException("Unsupported position: " + position);
}
return builder.create();
}
```
It is also possible to hide Back/Next/Complete buttons on each step if needed.
To do so you need to call `setBackButtonVisible(false)` and/or `setEndButtonVisible(false)` on
`StepViewModel.Builder` in your adapter.
### Subtitles in tabs
You can set a subtitle for each step in stepper with tabs, e.g. to mark a step as optional.
To do so you need to set the subtitle by calling `StepViewModel.Builder#setSubtitle(int)` or `StepViewModel.Builder#setSubtitle(CharSequence)`
in your adapter's `getViewModel` method.
### Custom styling
Basic styling can be done by choosing the active and inactive step colors.
There are some additional properties which can be changed directly from StepperLayout's attributes e.g. the background of bottom navigation buttons (see [StepperLayout attributes](#stepperlayout-attributes))
For advanced styling you can use `ms_stepperLayoutTheme` StepperLayout's attribute and provide your custom style to be used.
See 'Custom StepperLayout theme' in the sample app for an example.
### Using same stepper styling across the application
If you have many steppers in your application in different activities/fragments you might want to set a common style in a theme.
To do so, you need to set the `ms_stepperStyle` attribute in the theme, e.g.
```xml
```
and declare that style in the XML you keep your styles at, e.g.
```xml
```
### Showing a Back button on first step
By default if the user is on the first step then the Back button in the bottom navigation is hidden.
This behaviour can be changed by setting ```ms_showBackButtonOnFirstStep``` to ```true```, e.g.
```xml
```
To get a callback when this button was pressed you need set a ```StepperListener``` and write your own custom return logic in the ```onReturn()``` method to e.g. close the Activity.
### Using Views instead of Fragments as Steps
It is possible to use this library without the need to rely on Fragments.
To do so you need to use ```AbstractStepAdapter``` instead of ```AbstractFragmentStepAdapter```.
For an example of how to use it with views please see the sample app.
### Showing an error on tabs if step verification failed
To show an error in the tabbed stepper if step verification fails you need to set `ms_showErrorStateEnabled` attribute to `true`.
If you want to keep the error displayed when going back to the previous step you need to also set `ms_showErrorStateOnBackEnabled` to `true`.
If you want display an error message below the step title you need to set `ms_showErrorMessageEnabled` to `true`. The message set in `VerificationError` will be then displayed.
### Stepper feedback
It is possible to show stepper feedback for ongoing operations (see [Stepper feedback](https://material.io/guidelines/components/steppers.html#steppers-types-of-steppers)).
To do so you firstly need to set ```ms_stepperFeedbackType``` to one or more of:
* ```tabs``` - shows a progress message instead of the tabs during operation.
* ```content_progress``` - shows a progress bar on top of the steps' content.
* ```content_fade``` - partially fades the content out during operation (should not be used together with ```content_overlay```). You can change the default fade amount with `ms_stepperFeedback_contentFadeAlpha` attribute.
* ```content_overlay``` - shows a dimmed overlay over the content during the operation (should not be used together with ```content_fade```). You can change the overlay background with `ms_stepperFeedback_contentOverlayBackground` attribute.
* ```disabled_bottom_navigation``` - disables the buttons in the bottom navigation during operation. In order to see that the buttons are disabled on the bottom navigation bar, make sure that the button colors are assigned using color selectors with a disabled state (see the sample app).
* ```disabled_content_interaction``` - intercepts touch events on the steps' content and ignores them during operation.
The default is ```none``` which does nothing. It is possible to use multiple flags together.
After setting this to show the feedback you need to call ```StepperLayout#showProgress(@NonNull String progressMessage)```
and do hide the progress indicator you need to call ```StepperLayout#hideProgress()```.
E.g.
In layout:
```xml
```
and in BlockingStep:
```java
public class StepperFeedbackStepFragment extends Fragment implements BlockingStep {
//...
@Override
@UiThread
public void onNextClicked(final StepperLayout.OnNextClickedCallback callback) {
callback.getStepperLayout().showProgress("Operation in progress, please wait...");
new Handler().postDelayed(new Runnable() {
@Override
public void run() {
callback.goToNextStep();
callback.getStepperLayout().hideProgress();
}
}, 2000L);
}
//...
```
### Changing button text color when going to the next step should be disabled
It is possible to change the Next/Complete button's text color (together with right chevron's color)
when all the criteria to go to the next step are not met. This color should indicate that
the user cannot go to next step yet and look as if disabled. Clicking on the button will still perform the regular
step verification. There is a custom state added since setting `android:state_enabled` to `false` in a color selector would disable the clicks
and we want to have them so that we can show an info message for the user.
In order to set that color:
1. Create a new color selector in `res/color`
```xml
