Getting Started

Balloon 1.x (View)

This page documents Balloon 1.7.6, the last release of the View based library. For the current version see the Balloon 2.0.0 documentation and the Migration guide.

This guide covers the basics of creating and displaying Balloon tooltips in your Android application.

Installation

Add the dependency below to your module's build.gradle file:

GroovyKotlin

dependencies {
    implementation("com.github.skydoves:balloon:1.7.6")
}

dependencies {
    implementation("com.github.skydoves:balloon:1.7.6")
}

Creating a Balloon

Using Balloon.Builder

You can create a Balloon instance using the Balloon.Builder class:

val balloon = Balloon.Builder(context)
    .setWidthRatio(1.0f)
    .setHeight(BalloonSizeSpec.WRAP)
    .setText("Edit your profile here!")
    .setTextColorResource(R.color.white)
    .setTextSize(15f)
    .setIconDrawableResource(R.drawable.ic_edit)
    .setArrowPositionRules(ArrowPositionRules.ALIGN_ANCHOR)
    .setArrowSize(10)
    .setArrowPosition(0.5f)
    .setPadding(12)
    .setCornerRadius(8f)
    .setBackgroundColorResource(R.color.skyBlue)
    .setBalloonAnimation(BalloonAnimation.ELASTIC)
    .setLifecycleOwner(lifecycleOwner)
    .build()

Using Kotlin DSL

You can also create a Balloon using the Kotlin DSL with createBalloon:

val balloon = createBalloon(context) {
    setWidthRatio(1.0f)
    setHeight(BalloonSizeSpec.WRAP)
    setText("Edit your profile here!")
    setTextColorResource(R.color.white)
    setTextSize(15f)
    setIconDrawableResource(R.drawable.ic_edit)
    setArrowPositionRules(ArrowPositionRules.ALIGN_ANCHOR)
    setArrowSize(10)
    setArrowPosition(0.5f)
    setPadding(12)
    setCornerRadius(8f)
    setBackgroundColorResource(R.color.skyBlue)
    setBalloonAnimation(BalloonAnimation.ELASTIC)
    setLifecycleOwner(lifecycleOwner)
}

Using Java

Balloon balloon = new Balloon.Builder(context)
    .setArrowSize(10)
    .setArrowOrientation(ArrowOrientation.TOP)
    .setArrowPositionRules(ArrowPositionRules.ALIGN_ANCHOR)
    .setArrowPosition(0.5f)
    .setWidth(BalloonSizeSpec.WRAP)
    .setHeight(65)
    .setTextSize(15f)
    .setCornerRadius(4f)
    .setAlpha(0.9f)
    .setText("You can access your profile from now on.")
    .setTextColor(ContextCompat.getColor(context, R.color.white))
    .setIconDrawable(ContextCompat.getDrawable(context, R.drawable.ic_profile))
    .setBackgroundColor(ContextCompat.getColor(context, R.color.colorPrimary))
    .setOnBalloonClickListener(onBalloonClickListener)
    .setBalloonAnimation(BalloonAnimation.FADE)
    .setLifecycleOwner(lifecycleOwner)
    .build();

Width and Height

You can adjust the width and height of the Balloon using various approaches.

Specific Size

Set specific sizes regardless of the content:

Balloon.Builder(context)
    .setWidth(220)  // sets 220dp width
    .setHeight(160)  // sets 160dp height

Wrap Content

Set dynamic sizes depending on the content:

Balloon.Builder(context)
    .setWidth(BalloonSizeSpec.WRAP)  // width depends on content
    .setHeight(BalloonSizeSpec.WRAP)  // height depends on content

Screen Ratio

Set width based on the screen size ratio:

Balloon.Builder(context)
    .setWidthRatio(0.5f)  // 50% of the horizontal screen size

Padding and Margin

Padding

Adjust the content padding inside the Balloon:

Balloon.Builder(context)
    .setPadding(6)  // 6dp padding on all sides
    .setPaddingLeft(8)  // 8dp left padding
    .setPaddingTop(12)  // 12dp top padding
    .setPaddingRight(8)
    .setPaddingBottom(12)

Margin

Add margins to the Balloon container:

Balloon.Builder(context)
    .setMargin(12)  // margin on all sides
    .setMarginLeft(14)
    .setMarginRight(14)
    .setMarginHorizontal(14)  // left and right margins

Lifecycle Management

To avoid memory leaks, always set the lifecycle owner. The Balloon will automatically dismiss when the activity or fragment is destroyed:

Balloon.Builder(context)
    .setLifecycleOwner(lifecycleOwner)

Important

Always set the lifecycle owner to prevent memory leaks. Dialog and PopupWindow can leak memory if not properly dismissed before the activity is destroyed.

Lazy Initialization

You can initialize a Balloon lazily using the balloon() extension and a Balloon.Factory:

class CustomActivity : AppCompatActivity() {
    private val profileBalloon by balloon<ProfileBalloonFactory>()
}

Create a factory class that extends Balloon.Factory:

class ProfileBalloonFactory : Balloon.Factory() {

    override fun create(context: Context, lifecycle: LifecycleOwner): Balloon {
        return createBalloon(context) {
            setLayout(R.layout.layout_custom_profile)
            setArrowSize(10)
            setArrowOrientation(ArrowOrientation.TOP)
            setArrowPosition(0.5f)
            setWidthRatio(0.55f)
            setHeight(250)
            setCornerRadius(4f)
            setBackgroundColorResource(R.color.background)
            setBalloonAnimation(BalloonAnimation.CIRCULAR)
            setLifecycleOwner(lifecycle)
        }
    }
}

Note

The factory class must have a default (no-argument) constructor.