Android Stepper

A library for creating a wizard-like step-through user interface that uses navigation components and menus for displaying steps with advanced customization. The implementation is similar to what is done in Google's BottomNavigationView.

This project is also inspired by https://github.com/stepstone-tech/android-material-stepper

See the Sample app for a full range of the features and implementations of the library.

Jump to section

• Stepper Types
  • WIP
• Features
• Installation
• Usage
  • Create a Menu with the Steps
  • Create a Nav Graph with Step Fragments using corresponding menu item ids
  • Add StepperNavigationView to layout with the menu
  • Add NavHost fragment to layout with the nav graph
  • Setup Stepper with Navigation Controller
  • Add StepperNavListener to Activity (optional)
• Advanced Usage
  • Setup with Action Bar
  • Override back button to go up
  • Update Menu Programmatically
• XML Attributes
• Contributing
• License

Stepper Types

• Tabs

• Numbered Tabs

• Progress

• Fleets (Stories)

WIP

• Custom Icons Stepper

• Text-Only Stepper

Features

• AndroidX Navigation Components

• Fragment transition animations

• Color customization

• Multiple stepper types

Installation

Add the Jitpack repository to your root build.gradle

Gradle:

allprojects {
    repositories {
        // ...
        maven { url 'https://jitpack.io' }
    }
}

Kotlin DSL:

allprojects {
    repositories {
        // ...
        maven("https://jitpack.io")
    }
}

Add the dependency to your module

Gradle:

dependencies {
    implementation 'com.github.acefalobi:android-stepper:0.3.0'
}

Kotlin DSL:

dependencies {
    implementation("com.github.acefalobi:android-stepper:0.3.0")
}

Usage

Create a Menu with the Steps

<menu xmlns:android="http://schemas.android.com/apk/res/android">

    <item android:id="@+id/step_1_dest"
        android:title="Step 1" />

    <item android:id="@+id/step_2_dest"
        android:title="Step 2" />

    <item android:id="@+id/step_3_dest"
        android:title="Step 3" />

</menu>

Create a Nav Graph with Step Fragments using corresponding menu item ids

Remember to use the same ids for the menu and nav graph items.

<navigation xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/nav_stepper"
    app:startDestination="@id/step_1_dest">

    <fragment
        android:id="@+id/step_1_dest"
        android:name=".steps.Step1Fragment"
        android:label="Step 1" />

    <fragment
        android:id="@+id/step_2_dest"
        android:name=".steps.Step2Fragment"
        android:label="Step 2" />

    <fragment
        android:id="@+id/step_3_dest"
        android:name=".steps.Step3Fragment"
        android:label="Step 3" />

</navigation>

Add StepperNavigationView to layout with the menu

<com.aceinteract.android.stepper.StepperNavigationView
    android:id="@+id/stepper"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:stepperItems="@menu/menu_stepper"
    app:stepperType="@string/stepper_type_tab" />

See XML Attributes for full list of attributes.

Add NavHost fragment to layout with the nav graph

<fragment
    android:id="@+id/frame_stepper"
    android:name="androidx.navigation.fragment.NavHostFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:navGraph="@navigation/nav_stepper" />

Setup Stepper with Navigation Controller

val stepper = findViewById<StepperNavigationView>(R.id.stepper)
stepper.setupWithNavController(findNavController(R.id.frame_stepper))

Go back and forth between steps

stepper.goToPreviousStep()
stepper.goToNextStep()

Add StepperNavListener to Activity (optional)

class StepperActivity : AppCompatActivity(), StepperNavListener {

    override fun onStepChanged(step: Int) {
        Toast.makeText(this, "Step changed to: $step", Toast.LENGTH_SHORT).show()
    }

    override fun onCompleted() {
        Toast.makeText(this, "Stepper completed", Toast.LENGTH_SHORT).show()
    }

}

stepperNavListener = this

Advanced Usage

Setup with Action Bar

Setup action bar with top-level destinations so that the action bar title changes with the steps.

setupActionBarWithNavController(
    findNavController(R.id.frame_stepper),
    AppBarConfiguration.Builder(
        R.id.step_1_dest,
        R.id.step_2_dest,
        R.id.step_3_dest
    ).build()
)

If you want to override the up navigation with the nav controller

setupActionBarWithNavController(findNavController(R.id.frame_stepper))

override fun onSupportNavigateUp(): Boolean =
    findNavController(R.id.frame_stepper).navigateUp()

Override back button to go up

override fun onBackPressed() {
    if (stepper.currentStep == 0) {
        super.onBackPressed()
    } else {
        findNavController(R.id.frame_stepper).navigateUp()
    }
}

Update Menu Programmatically

First make sure the menu item already has corresponding destination in the nav graph.

stepper.menu.add(groupId, R.id.step_4_dest, order, "New Step")

XML Attributes

Contributing

See CONTRIBUTING.md for contributing guidelines

TODO

• Add more stepper types

• Write tests.

• Setup CI to automate testing

• Publish as package

License

Copyright 2020 Ayomide Falobi

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.