Custom GridView in Android with Images and Text (Step-by-Step)

Step 2: Add the GridView to activity_main.xml

Open res/layout/activity_main.xml and replace its content with:

<?xml version="1.0" encoding="utf-8"?>
<GridView xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/grid"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:padding="8dp"
    android:numColumns="3"
    android:horizontalSpacing="8dp"
    android:verticalSpacing="8dp"
    android:stretchMode="columnWidth"
    android:gravity="center" />

• numColumns sets the number of columns. Use auto_fit with columnWidth if you want it to adjust to screen size.
• horizontalSpacing and verticalSpacing add space between items.
• stretchMode="columnWidth" spreads columns evenly across the screen.

Step 3: Create the grid item layout

Right-click res/layout, choose New → Layout Resource File, and name it grid_item.xml. Each item is an image with a title under it:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:orientation="vertical"
    android:gravity="center_horizontal"
    android:padding="4dp">

    <ImageView
        android:id="@+id/imageView"
        android:layout_width="match_parent"
        android:layout_height="100dp"
        android:scaleType="centerCrop"
        android:contentDescription="@null" />

    <TextView
        android:id="@+id/textView"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginTop="6dp"
        android:textSize="14sp"
        android:textStyle="bold" />
</LinearLayout>

A vertical LinearLayout keeps the title under the image on every screen size, with no hard-coded margins.

Step 4: Create the adapter

The adapter is the bridge between your data and the grid. It tells the GridView how many items there are and builds the view for each one.

Create a new Java class called GridAdapter:

package com.example.customgrid;

import android.content.Context;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import android.widget.BaseAdapter;
import android.widget.ImageView;
import android.widget.TextView;

public class GridAdapter extends BaseAdapter {

    private final Context context;
    private final int[] images;
    private final String[] titles;

    public GridAdapter(Context context, int[] images, String[] titles) {
        this.context = context;
        this.images = images;
        this.titles = titles;
    }

    @Override
    public int getCount() {
        return titles.length;
    }

    @Override
    public Object getItem(int position) {
        return titles[position];
    }

    @Override
    public long getItemId(int position) {
        return position;
    }

    @Override
    public View getView(int position, View convertView, ViewGroup parent) {
        ViewHolder holder;

        if (convertView == null) {
            convertView = LayoutInflater.from(context)
                    .inflate(R.layout.grid_item, parent, false);
            holder = new ViewHolder();
            holder.image = convertView.findViewById(R.id.imageView);
            holder.title = convertView.findViewById(R.id.textView);
            convertView.setTag(holder);
        } else {
            holder = (ViewHolder) convertView.getTag();
        }

        holder.image.setImageResource(images[position]);
        holder.title.setText(titles[position]);
        return convertView;
    }

    private static class ViewHolder {
        ImageView image;
        TextView title;
    }
}

Why this version is better than the basic one you’ll see in many tutorials:

• It reuses views. convertView is only inflated when it’s null. When you scroll, Android hands back views that went off screen, so the grid stays smooth.
• ViewHolder saves the findViewById calls, so they run once per view, not on every scroll.
• inflate(..., parent, false) keeps the layout parameters from grid_item.xml. Passing null drops them.
• getItem and getItemId return real values, which you need for click handling.

Replace com.example.customgrid with your own package name.

Step 5: Connect it in MainActivity

package com.example.customgrid;

import android.os.Bundle;
import android.widget.GridView;
import android.widget.Toast;
import androidx.appcompat.app.AppCompatActivity;

public class MainActivity extends AppCompatActivity {

    private final int[] images = {
            R.drawable.cricket, R.drawable.basketball, R.drawable.football,
            R.drawable.hockey, R.drawable.baseball, R.drawable.tennis
    };

    private final String[] titles = {
            "Cricket", "Basketball", "Football", "Hockey", "Baseball", "Tennis"
    };

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        GridView gridView = findViewById(R.id.grid);
        gridView.setAdapter(new GridAdapter(this, images, titles));

        gridView.setOnItemClickListener((parent, view, position, id) ->
                Toast.makeText(this, "You clicked " + titles[position],
                        Toast.LENGTH_SHORT).show());
    }
}

Run the app and you’ll see a three-column grid of sports. Tap any item to see its name in a toast. OnItemClickListener is a Java interface. If that’s new to you, see what an interface is in Java.

[Keep the existing result screenshots here]

The same adapter in Kotlin

Google recommends Kotlin for new Android apps. Here’s the same grid in Kotlin:

class GridAdapter(
    private val context: Context,
    private val images: IntArray,
    private val titles: Array<String>
) : BaseAdapter() {

    override fun getCount() = titles.size
    override fun getItem(position: Int) = titles[position]
    override fun getItemId(position: Int) = position.toLong()

    override fun getView(position: Int, convertView: View?, parent: ViewGroup): View {
        val view: View
        val holder: ViewHolder

        if (convertView == null) {
            view = LayoutInflater.from(context).inflate(R.layout.grid_item, parent, false)
            holder = ViewHolder(view.findViewById(R.id.imageView), view.findViewById(R.id.textView))
            view.tag = holder
        } else {
            view = convertView
            holder = view.tag as ViewHolder
        }

        holder.image.setImageResource(images[position])
        holder.title.text = titles[position]
        return view
    }

    private class ViewHolder(val image: ImageView, val title: TextView)
}

class MainActivity : AppCompatActivity() {

    private val images = intArrayOf(
        R.drawable.cricket, R.drawable.basketball, R.drawable.football,
        R.drawable.hockey, R.drawable.baseball, R.drawable.tennis
    )
    private val titles = arrayOf("Cricket", "Basketball", "Football", "Hockey", "Baseball", "Tennis")

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val gridView = findViewById<GridView>(R.id.grid)
        gridView.adapter = GridAdapter(this, images, titles)
        gridView.setOnItemClickListener { _, _, position, _ ->
            Toast.makeText(this, "You clicked ${titles[position]}", Toast.LENGTH_SHORT).show()
        }
    }
}

GridView vs RecyclerView: which should you use?

GridView still works and is fine for small, simple grids. For new apps, most developers use RecyclerView with a GridLayoutManager, because it’s more flexible and is the approach Android’s docs recommend for scrolling lists (Create dynamic lists with RecyclerView).

Switching the grid part is one line:

recyclerView.setLayoutManager(new GridLayoutManager(this, 3));

If your app uses Jetpack Compose, the Compose equivalent is LazyVerticalGrid (Lazy grids).

Common errors and fixes

• The app crashes with a NullPointerException in getView. Check that the IDs in grid_item.xml (imageView, textView) match the ones in your adapter.
• XML errors after copying code from a website. Look for curly quotes (“ ”). Android Studio only accepts straight quotes (“).
• Items overlap or look squashed. Use wrap_content height on the item’s root layout and set the spacing on the GridView.
• Images don’t show. Make sure the files are in res/drawable with lowercase names and no spaces or hyphens.
• Clicks don’t work. If your item has a Button or CheckBox, it can take focus. Add android:focusable="false" to it.
• Scrolling is slow. You’re probably inflating a new view every time. Use the convertView check and ViewHolder shown above.

Watch the video tutorial