Introduction

TextView supports compound drawables on the start, top, end, and bottom sides of the text. If you want to add an icon programmatically, the cleanest approach is usually to load the drawable and call one of the compound-drawable setter methods.

Use the relative API for modern layouts

On current Android projects, prefer the relative start and end methods rather than hard-coded left and right methods. That keeps the UI correct in right-to-left layouts.

1import androidx.appcompat.content.res.AppCompatResources
2
3val drawable = AppCompatResources.getDrawable(this, R.drawable.ic_search)
4
5textView.setCompoundDrawablesRelativeWithIntrinsicBounds(
6    drawable,
7    null,
8    null,
9    null
10)
11textView.compoundDrawablePadding = 16

This places the drawable at the start side of the text and uses the drawable's intrinsic size. If your app supports Arabic, Hebrew, or any other right-to-left language, this is the correct default because start adapts while left does not.

When you need explicit bounds

If you call setCompoundDrawables instead of the WithIntrinsicBounds variant, you must set the drawable bounds yourself or nothing may appear.

1val drawable = AppCompatResources.getDrawable(this, R.drawable.ic_warning)!!
2drawable.setBounds(0, 0, drawable.intrinsicWidth, drawable.intrinsicHeight)
3
4textView.setCompoundDrawablesRelative(drawable, null, null, null)

That requirement surprises many developers. The intrinsic-bounds helper exists precisely to avoid this extra step when the built-in size is acceptable.

Handling size, tint, and spacing

A runtime drawable often needs to match the current theme or text appearance. In those cases, size and tint matter as much as the actual setter method.

1import androidx.core.content.ContextCompat
2import androidx.core.graphics.drawable.DrawableCompat
3
4val drawable = AppCompatResources.getDrawable(this, R.drawable.ic_info)?.mutate()
5if (drawable != null) {
6    DrawableCompat.setTint(drawable, ContextCompat.getColor(this, R.color.teal_700))
7    textView.setCompoundDrawablesRelativeWithIntrinsicBounds(drawable, null, null, null)
8    textView.compoundDrawablePadding = resources.getDimensionPixelSize(R.dimen.spacing_small)
9}

Using a dimension resource for padding is usually better than hard-coding pixels. It keeps spacing consistent across densities and lets design changes happen in one place.

Why not use XML all the time

XML drawables are fine when the icon is static. Programmatic assignment is useful when the icon depends on state, theme, validation result, or data loaded at runtime. For example, a TextView can show a warning icon only when a field is invalid, or swap icons when the user changes a filter.

The API is also shared across TextView subclasses such as Button and EditText, so the same pattern works in several common widgets. That makes it a good tool to know even if your immediate use case is just one text label.

Clearing and updating drawables safely

In reusable views such as rows inside a RecyclerView, remember that a TextView may already have an old compound drawable attached from a previous bind. If one state shows an icon and another state should not, clear the drawable explicitly by passing null for that side. Compound drawables behave like normal view state, so recycled widgets keep them until you replace or remove them.

Common Pitfalls

• Using left and right APIs when start and end are the better choice for right-to-left support.
• Calling setCompoundDrawables without setting bounds first.
• Forgetting compoundDrawablePadding, which makes the icon look glued to the text.
• Loading a very large bitmap drawable and letting it dominate the line height.
• Assuming XML and code paths behave identically when tinting and runtime theme changes are involved.

Summary

• Use compound drawables to attach an icon directly to a TextView.
• Prefer setCompoundDrawablesRelativeWithIntrinsicBounds for modern Android layouts.
• Use the intrinsic-bounds helper unless you intentionally need custom drawable sizing.
• Switch to programmatic assignment when the icon depends on runtime state.
• Remember padding, tint, and right-to-left behavior, not just the drawable resource itself.