ViewPager2

Why ViewPager2 Replaced ViewPager

The original ViewPager had two architectural problems: it only supported horizontal scrolling, and its adapter management was error-prone. ViewPager2 fixes both by:

• Supporting both horizontal and vertical scrolling
• Using RecyclerView's adapter architecture (ListAdapter + DiffUtil)
• Supporting RTL (right-to-left) layouts natively
• Providing better Fragment lifecycle management

Adding ViewPager2

Add the dependency:

dependencies {
    implementation("androidx.viewpager2:viewpager2:1.1.0")
}

Basic XML Setup

<androidx.viewpager2.widget.ViewPager2
    android:id="@+id/viewPager"
    android:layout_width="match_parent"
    android:layout_height="0dp"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintBottom_toBottomOf="parent" />

Fragment-Based Pages

ViewPager2 works with Fragments via FragmentStateAdapter. Each page is a Fragment, and the adapter manages their lifecycle:

class OnboardingAdapter(fragment: Fragment) : FragmentStateAdapter(fragment) {
    override fun getItemCount() = 3

    override fun createFragment(position: Int): Fragment {
        return when (position) {
            0 -> WelcomeFragment()
            1 -> FeaturesFragment()
            2 -> GetStartedFragment()
            else -> throw IllegalArgumentException("Invalid position: $position")
        }
    }
}

Set it up in your Fragment:

class OnboardingFragment : Fragment() {
    private var _binding: FragmentOnboardingBinding? = null
    private val binding get() = _binding!!

    override fun onCreateView(
        inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?
    ): View {
        _binding = FragmentOnboardingBinding.inflate(inflater, container, false)
        return binding.root
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        binding.viewPager.adapter = OnboardingAdapter(this)
    }

    override fun onDestroyView() {
        super.onDestroyView()
        _binding = null
    }
}

RecyclerView-Based Pages

ViewPager2 also supports non-Fragment pages using RecyclerView adapters. Use this when your pages are simple views, not Fragments:

class ImagePagerAdapter(
    private val images: List<Int>
) : RecyclerView.Adapter<ImagePagerAdapter.ImageViewHolder>() {

    inner class ImageViewHolder(private val imageView: ImageView) :
        RecyclerView.ViewHolder(imageView) {
        fun bind(resId: Int) {
            imageView.setImageResource(resId)
        }
    }

    override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): ImageViewHolder {
        val imageView = ImageView(parent.context).apply {
            layoutParams = ViewGroup.LayoutParams(
                ViewGroup.LayoutParams.MATCH_PARENT,
                ViewGroup.LayoutParams.MATCH_PARENT
            )
            scaleType = ImageView.ScaleType.CENTER_CROP
        }
        return ImageViewHolder(imageView)
    }

    override fun onBindViewHolder(holder: ImageViewHolder, position: Int) {
        holder.bind(images[position])
    }

    override fun getItemCount() = images.size
}

Listening to Page Changes

binding.viewPager.registerOnPageChangeCallback(object : ViewPager2.OnPageChangeCallback() {
    override fun onPageSelected(position: Int) {
        // Update UI when page changes (e.g., highlight tab)
    }

    override fun onPageScrolled(position: Int, positionOffset: Float, positionOffsetPixels: Int) {
        // Animate elements based on scroll position
    }

    override fun onPageScrollStateChanged(state: Int) {
        // SCROLL_STATE_IDLE, SCROLL_STATE_DRAGGING, SCROLL_STATE_SETTLING
    }
})

TabLayout + ViewPager2

TabLayout provides tab indicators above or below the ViewPager2. Connect them with TabLayoutMediator:

<com.google.android.material.tabs.TabLayout
    android:id="@+id/tabLayout"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

<androidx.viewpager2.widget.ViewPager2
    android:id="@+id/viewPager"
    android:layout_width="match_parent"
    android:layout_height="0dp"
    app:layout_constraintTop_toBottomOf="@id/tabLayout"
    app:layout_constraintBottom_toBottomOf="parent" />

TabLayoutMediator(binding.tabLayout, binding.viewPager) { tab, position ->
    tab.text = when (position) {
        0 -> "Home"
        1 -> "Search"
        2 -> "Profile"
        else -> ""
    }
    // Optional: set tab icon instead of text
    // tab.setIcon(R.drawable.ic_home)
}.attach()

Tab Modes

Set in XML:

<com.google.android.material.tabs.TabLayout
    app:tabMode="scrollable"
    app:tabGravity="fill" />

Page Transformations

Animate page transitions with setPageTransformer:

binding.viewPager.setPageTransformer { page, position ->
    // Simple depth effect
    page.alpha = when {
        position < -1 -> 0f
        position <= 0 -> 1f
        position <= 1 -> 1f - position
        else -> 0f
    }

    // Parallax effect
    page.translationX = position * -50

    // Scale effect
    val scale = 1f - abs(position) * 0.2f
    page.scaleX = scale
    page.scaleY = scale
}

The position parameter represents the page's relative position: 0 means fully visible, -1 means off-screen left, 1 means off-screen right. Intermediate values represent partially visible pages.

ViewPager2 vs ViewPager vs HorizontalScrollView

Always prefer ViewPager2 for new projects. ViewPager is deprecated.