Historically, accessibility has often been treated as an afterthought. Something to consider only if time permitted before a release.

Today, that perspective has fundamentally changed. With regulations like the European Accessibility Act (EAA) taking effect across European Union markets, building accessible software is increasingly a legal and business requirement.

More importantly, building accessible applications is just good engineering. Accessible apps improve usability for all users and help make sure that you're not excluding a substantial portion of your potential audience.

Jetpack Compose simplifies accessibility compared to the traditional Android View system. Because Compose is declarative and state-driven, it manages semantic metadata alongside your visual user interface.

In this comprehensive guide, you will learn how accessibility works in Jetpack Compose, how to use the Semantics tree, how to apply essential and advanced accessibility patterns, and how to thoroughly test your apps using automated tests, Google's Accessibility Scanner, Android Studio's Layout Inspector, and TalkBack.

Prerequisites

To follow along with this guide, you'll need:

• Basic familiarity with Kotlin and Jetpack Compose (such as Composables, Modifiers, and State).

• Android Studio (Hedgehog, Iguana, Jellyfish, Koala, Ladybug, or newer).

• An Android device or emulator running Android 9.0 (API 28) or higher with access to the Google Play Store (to install and run the current version of Google Accessibility Scanner).

Table of Contents

• Prerequisites

• Why Accessibility Matters in Modern Android Development

• Core Concepts of Android Accessibility

• Semantics in Jetpack Compose

• Essential Accessibility Practices

• Advanced Accessibility Techniques

• How to Test and Debug Accessibility

• Real-World Accessible UI Patterns

• Accessibility Audit Checklist

• Conclusion and Next Steps

• Essential Resources

Why Accessibility Matters in Modern Android Development

According to the World Health Organization (WHO), more than 1.3 billion people (representing roughly 16% of the global population) live with a significant disability. This includes people with permanent visual impairments, hearing loss, physical motor limitations, and cognitive or neurological differences.

In addition to permanent disabilities, users can often experience temporary or situational limitations. A person holding a baby with one hand has temporary motor constraints. Someone using their phone in harsh midday sunlight experiences situational visual impairment. And someone in a loud airport terminal experiences situational hearing limitations.

Designing an accessible app ensures that your interface remains resilient and usable across all of these scenarios and more.

Beyond empathy and inclusive design, accessibility is increasingly governed by international law.

In the European Union, the European Accessibility Act (EAA) mandates accessibility for a defined list of products and services, including smartphones and computers, e-commerce, consumer banking services, e-books, and passenger transport services. In practice, conformity is typically demonstrated against EN 301 549, the European accessibility standard for digital products and services.

In the United States, the Americans with Disabilities Act (ADA) applies to state and local governments (Title II, which, since 2024, has an explicit web and mobile app rule requiring compliance with WCAG 2.1 Level AA) and to public accommodations (Title III). Separately, Section 508 of the Rehabilitation Act requires federal agencies' information and communications technology to be accessible.

Failing to meet these standards can result in legal penalties and brand damage. Conversely, prioritizing accessibility expands your total addressable market and boosts user retention.

Quality also affects distribution: Google's Android vitals documentation notes that a high user-perceived crash rate hurts your app's discoverability on Google Play.

Core Concepts of Android Accessibility

To design accessible applications in Jetpack Compose, you must understand how the underlying Android operating system communicates with assistive technologies.

Understanding Android Accessibility Services

Android includes several built-in accessibility services that run as background processes. These services intercept the app's user interface and translate it into alternative sensory feedback or alternative input mechanisms:

• TalkBack (Screen Reader): TalkBack is Android's built-in screen reader designed for blind and low-vision users. It inspects your interface elements, converts visual content and semantic descriptions into synthesized speech and haptic vibrations, and enables non-visual navigation using linear swipe gestures.

• Switch Access: Designed for users with severe motor impairments who can't use a physical touch screen, Switch Access allows users to control their device using one or more physical switches (such as foot pedals, sip-and-puff devices, or single buttons) or a connected keyboard. It scans through focusable screen elements sequentially, allowing the user to select items when highlighted.

• Voice Access: Allows users to control their entire phone using spoken commands (such as "Tap Open," "Scroll down," or "Type hello"). It assigns numeric badges to interactive elements based on their accessibility labels so users can trigger actions by number.

• Select to Speak: Allows users to highlight specific paragraphs, buttons, or icons on the screen to hear them spoken aloud without turning on full TalkBack navigation.

All of these accessibility services share one common requirement: they don't interact directly with visual pixels. Instead, they read the Semantics Tree generated by your application.

How the Compose Semantics Tree Works

When you build a user interface in Jetpack Compose, Compose generates two separate but linked internal tree structures:

1. The Layout (UI) Tree: This tree contains the visual rendering nodes that measure, place, and draw pixels on the screen (such as Canvas, Box, Row, Column, Text, and Image).

2. The Semantics Tree: This tree runs in parallel with the Layout tree. It contains metadata that describes the meaning, purpose, state, and interactive capabilities of each element.

Standard Material Compose components (such as Button, Checkbox, Slider, Switch, and Text) automatically populate appropriate semantic properties into the Semantics tree. For example, a Button composable automatically sets its role to Role.Button and attaches a click action.

But when you build custom layouts, canvas drawings, or non-standard interactive widgets, Compose can't automatically infer your design intent. In those cases, you must use Compose's semantic modifiers to enrich the Semantics tree manually.

The WCAG 2.1 POUR Principles

The international benchmark for digital accessibility is the Web Content Accessibility Guidelines (WCAG) 2.1, published by the World Wide Web Consortium (W3C). These guidelines are organized around four core principles known by the acronym POUR:

• Perceivable: Information and UI components must be presentable to users in ways they can perceive. Content can't be invisible to all of a user's senses. In Android apps, this means providing descriptive text alternatives for all visual media, supporting dynamic font scaling, and maintaining high color contrast.

• Operable: User interface components and navigation must be operable. Users must be able to perform all interactions regardless of whether they use a touchscreen, a hardware keyboard, voice commands, or a switch device. This requires adequate touch targets (Android's guideline is at least 48dp × 48dp) and logical navigation orders.

• Understandable: Users must be able to understand both the information and the interface's operation. This means writing clear labels, providing meaningful validation error messages, avoiding sudden unexpected layout shifts, and structuring forms predictably.

• Robust: Content must be sufficiently robust to be reliably interpreted by a wide variety of user agents and assistive technologies. In Compose, this means avoiding hacky workarounds, using standard semantic roles, and honoring system-level user preferences.

Semantics in Jetpack Compose

In this section, we'll examine how Compose exposes and manipulates semantic metadata.

What Are Semantics?

Semantics in Jetpack Compose are key-value properties attached to layout nodes using the Modifier.semantics modifier. They convey information such as:

• What an element is called (contentDescription)

• What kind of UI control it represents (role = Role.Checkbox, Role.Button, Role.Tab)

• What state it currently holds (stateDescription = "Checked", progressBarRangeInfo)

• What actions the user can perform (onClick, onLongClick, customActions)

Basic Semantic Properties and Content Descriptions

The most widely used semantic property is contentDescription. It provides a localized textual representation of non-textual UI elements, such as icons, photographs, and vector graphics.

Here's how you provide content descriptions for visual components:

// A functional icon button that performs an action
IconButton(onClick = { /* Open camera */ }) {
    Icon(
        painter = painterResource(id = R.drawable.ic_camera),
        contentDescription = "Open camera"
    )
}

// A decorative background illustration
Image(
    painter = painterResource(id = R.drawable.decorative_pattern),
    contentDescription = null, // Informs TalkBack to skip this node completely
    modifier = Modifier.fillMaxWidth()
)

How It Works Under the Hood

When TalkBack navigates to the Icon, it reads the contentDescription aloud (something like "Open camera, button, double tap to activate"). TalkBack automatically appends the word "button" because IconButton exposes Role.Button. (Exact TalkBack phrasing varies by version and locale. The spoken examples throughout this guide are illustrative.)

For decorative elements (such as subtle background shapes, divider lines, or visual illustrations that accompany adjacent descriptive text), you should explicitly set contentDescription = null. Setting contentDescription = null instructs Compose to omit that element from the Semantics tree, preventing screen readers from stopping on meaningless visual noise.

Custom Semantics and State Descriptions

When an element changes its state dynamically (such as toggling between playing and paused, or expanded and collapsed), screen reader users need to be notified of the current state before they interact with it.

You can set stateDescription and role inside the Modifier.semantics block:

var isPlaying by remember { mutableStateOf(false) }

IconButton(
    onClick = { isPlaying = !isPlaying },
    modifier = Modifier.semantics {
        // Explicitly declare what state the media player is in
        stateDescription = if (isPlaying) "Playing audio" else "Audio paused"
        role = Role.Button
    }
) {
    Icon(
        imageVector = if (isPlaying) Icons.Default.Pause else Icons.Default.PlayArrow,
        contentDescription = if (isPlaying) "Pause" else "Play"
    )
}

How It Works Under the Hood

Without stateDescription, TalkBack only reads the action ("Play, button"). The user has to guess whether the audio is currently playing or stopped.

By adding stateDescription, TalkBack announces: "Playing audio, Pause, button, double-tap to toggle." This gives the user immediate confirmation of the current state followed by the action that activating the control will perform.

How to Merge Semantics with mergeDescendants

In complex layouts, multiple individual composables often combine to represent a single logical entity. For instance, a user profile row might contain an avatar image, a username, an online badge, and a timestamp.

By default, TalkBack will treat every child Text and Image node as an independent stop, forcing the user to swipe four or five times just to move past a single list item.

You can use Modifier.semantics(mergeDescendants = true) to combine all descendant nodes into a single, cohesive accessibility node:

// Bad: TalkBack focuses three separate times: "Star icon", "4.5", "Customer rating"
Row(modifier = Modifier.clickable { /* Navigate to reviews */ }) {
    Icon(
        imageVector = Icons.Default.Star,
        contentDescription = "Star icon"
    )
    Text(text = "4.5")
    Text(text = "Customer rating")
}

// Good: Merged into one single stop: "Customer rating: 4.5 out of 5 stars, button"
Row(
    modifier = Modifier
        .clickable(onClickLabel = "View all reviews") { /* Navigate to reviews */ }
        .semantics(mergeDescendants = true) {
            contentDescription = "Customer rating: 4.5 out of 5 stars"
        }
) {
    Icon(
        imageVector = Icons.Default.Star,
        contentDescription = null // Suppressed because parent provides full description
    )
    Text(text = "4.5")
    Text(text = "Customer rating")
}

How It Works Under the Hood

When mergeDescendants = true is set, Compose collapses the accessibility boundaries of all child composables. Instead of generating multiple stops in the Semantics tree, Compose exposes a single node to the accessibility framework. TalkBack focuses the entire Row as a single bounding box and reads the parent's contentDescription.

How to Clear Semantics with clearAndSetSemantics

In certain situations, a standard composable may include default semantic behaviors that interfere with your intended accessibility experience.

The Modifier.clearAndSetSemantics modifier clears all semantic properties that would otherwise be inherited from child composables or default implementations, allowing you to define a clean, custom semantic definition:

// A composite badge displaying notification count
Box(
    modifier = Modifier.clearAndSetSemantics {
        contentDescription = "3 unread messages"
        role = Role.Button
    }
) {
    Icon(
        imageVector = Icons.Default.Email,
        contentDescription = "Email icon" // Cleared and ignored
    )
    Text(text = "3") // Cleared and ignored
}

How It Works Under the Hood

Unlike Modifier.semantics, which adds or overrides specific keys, clearAndSetSemantics discards all existing keys generated by the composable subtree. In the example above, the separate "Email icon" and "3" text nodes are completely erased from the Semantics tree and replaced with the single announcement: "3 unread messages, button."

Essential Accessibility Practices

Now we'll cover the core accessibility practices you should implement in your applications, along with explanations of why each practice matters.

How to Write Meaningful Content Descriptions

A content description should concisely explain the purpose or action of an element rather than its visual appearance.

What to Do (Recommended Practice)

// Descriptive, action-oriented label
IconButton(onClick = { deleteDraft() }) {
    Icon(
        imageVector = Icons.Default.Delete,
        contentDescription = "Delete draft message"
    )
}

// Contextual weather information
Image(
    painter = painterResource(R.drawable.weather_sunny),
    contentDescription = "Current weather: Sunny, 75 degrees Fahrenheit"
)

The icon description tells the user exactly what will happen when they tap the button ("Delete draft message"). The weather image communicates the actual underlying data rather than describing the art style.

What Not to Do (Antipattern)

// Avoid generic or redundant descriptions
IconButton(onClick = { deleteDraft() }) {
    Icon(
        imageVector = Icons.Default.Delete,
        contentDescription = "Trash can icon button" // Bad: includes visual style and element type
    )
}

// Avoid empty strings on interactive elements
IconButton(onClick = { openSettings() }) {
    Icon(
        imageVector = Icons.Default.Settings,
        contentDescription = "" // Bad: leaves the button with no accessible label
    )
}

Including words like "icon" or "button" is redundant because TalkBack already announces the component's role. Using an empty string ("") on an interactive element leaves TalkBack with nothing meaningful to announce (typically read out as an unlabeled button), giving screen reader users zero context about what the button does. Compose's accessibility checks treat an empty content description the same as a missing one.

How to Ensure Minimum Touch Target Sizes

Google's Material Design and Android accessibility guidelines require all interactive elements to have a minimum touch target size of at least 48dp × 48dp, which corresponds to a physical size of about 9mm. This is squarely within the 7–10mm range Google recommends for touchscreen targets.

For comparison, WCAG itself sets lower web-oriented baselines: WCAG 2.1 Success Criterion 2.5.5 requires 44×44 CSS pixels at Level AAA, and WCAG 2.2 Success Criterion 2.5.8 requires 24×24 CSS pixels at Level AA. The 48dp rule is Android's stricter platform standard.

What to Do (Recommended Practice)

// Method A: Using minimumInteractiveComponentSize()
Box(
    modifier = Modifier
        .minimumInteractiveComponentSize() // Expands touch area to 48dp x 48dp
        .clickable { /* Toggle bookmark */ }
) {
    Icon(
        imageVector = Icons.Default.Bookmark,
        contentDescription = "Bookmark article",
        modifier = Modifier.size(24.dp) // Visual size is 24dp, touch target is 48dp
    )
}

// Method B: Standard IconButton (built-in 48dp target)
IconButton(onClick = { /* Toggle bookmark */ }) {
    Icon(
        imageVector = Icons.Default.Bookmark,
        contentDescription = "Bookmark article"
    )
}

Modifier.minimumInteractiveComponentSize() allows your visual design to remain compact (for instance, a 24dp icon) while ensuring that the invisible, clickable hit box expands to 48dp × 48dp. This prevents touch misses for users with motor tremors or limited fine motor control.

What Not to Do (Antipattern)

// Bad: Tightly constrained 20dp clickable area
Icon(
    imageVector = Icons.Default.Close,
    contentDescription = "Close dialog",
    modifier = Modifier
        .size(20.dp)
        .clickable { dismissDialog() } // Touch target is strictly 20dp x 20dp!
)

A 20dp touch target is nearly impossible to tap reliably, especially on high-density displays or while walking. Google's Accessibility Scanner will flag it as a touch target issue.

How to Maintain Accessible Color Contrast Ratios

Color contrast measures the difference in luminance between foreground text and its background. If the contrast ratio is too low, people with low vision, color blindness, or older eyes will likely not be able to read your text.

WCAG 2.1 defines the following minimum contrast ratios (Android's accessibility documentation maps WCAG's point sizes to sp):

• Normal text (smaller than 18sp, or smaller than 14sp bold): Minimum 4.5:1

• Large text (18sp or larger, or 14sp bold or larger): Minimum 3.0:1

• UI components and graphical objects: Minimum 3.0:1

What to Do (Recommended Practice)

// Using Material 3 color tokens (paired roles maintain usable contrast)
Text(
    text = "Account Overview",
    color = MaterialTheme.colorScheme.onPrimaryContainer,
    modifier = Modifier.background(MaterialTheme.colorScheme.primaryContainer)
)

// Explicit high-contrast colors (for example, Black on White = 21:1 ratio)
Text(
    text = "Order Confirmed",
    color = Color(0xFF1B5E20), // Dark green
    modifier = Modifier.background(Color(0xFFE8F5E9)) // Light green tint
)

Material 3 color tokens (such as onPrimaryContainer paired with primaryContainer) are generated by the Material color system so that "on" colors maintain usable contrast against their paired container colors across both light and dark themes. You should still verify contrast for any custom brand colors you override.

What Not to Do (Antipattern)

// Bad: Light gray on pure white (Contrast ratio ~ 1.6:1 - Fails WCAG)
Text(
    text = "Terms and Conditions apply",
    color = Color(0xFFB0B0B0),
    modifier = Modifier.background(Color.White)
)

Light gray text on a white background is one of the most common accessibility violations on the mobile web and in native apps. Sighted users in bright ambient light and users with low vision can't read this text.

How to Provide Custom Clickable Labels

When a user navigates to a clickable element using TalkBack, the screen reader appends default instructions such as "Double-tap to activate."

You can customize this instruction using the onClickLabel parameter in Modifier.clickable to describe the precise outcome of the interaction.

What to Do (Recommended Practice)

ListItem(
    headlineContent = { Text("Wi-Fi Networks") },
    supportingContent = { Text("Connected to Office_5G") },
    modifier = Modifier.clickable(
        onClickLabel = "Open Wi-Fi network settings"
    ) {
        navigateToWifiSettings()
    }
)

TalkBack will announce: "Wi-Fi Networks, Connected to Office_5G, double-tap to open Wi-Fi network settings." The user knows exactly what will happen before committing to the action.

What Not to Do (Antipattern)

// Bad: Generic clickable element without context
Card(
    modifier = Modifier.clickable { openInvoiceDetails() }
) {
    Text("Invoice #4092")
}

TalkBack announces: "Invoice #4092, double-tap to activate." The user is left uncertain whether tapping will pay the invoice, download a PDF, or open an edit screen.

How to Establish Heading Hierarchies

Visual readers scan large, bold text headings to understand a screen's layout and hierarchy. Screen reader users need the exact same structural overview.

By applying the heading() semantic modifier, you designate a text node as an accessibility heading. TalkBack users can change their navigation mode to "Headings" and quickly swipe up or down to jump between sections.

What to Do (Recommended Practice)

Column(modifier = Modifier.padding(16.dp)) {
    // Screen title heading
    Text(
        text = "Security Settings",
        style = MaterialTheme.typography.headlineMedium,
        modifier = Modifier.semantics { heading() }
    )

    Spacer(modifier = Modifier.height(16.dp))

    // Section 1 heading
    Text(
        text = "Two-Factor Authentication",
        style = MaterialTheme.typography.titleMedium,
        modifier = Modifier.semantics { heading() }
    )
    
    // Section 1 content...

    Spacer(modifier = Modifier.height(16.dp))

    // Section 2 heading
    Text(
        text = "Connected Devices",
        style = MaterialTheme.typography.titleMedium,
        modifier = Modifier.semantics { heading() }
    )
    
    // Section 2 content...
}

TalkBack users can bypass dozens of individual switches and descriptions to jump directly to "Connected Devices" in seconds.

What Not to Do (Antipattern)

// Bad: Visual heading without semantic markup
Text(
    text = "Two-Factor Authentication",
    style = MaterialTheme.typography.titleLarge // Visually large, but invisible as a heading to TalkBack
)

Without semantics { heading() }, TalkBack treats the text as regular body copy, preventing users from navigating by headings.

How to Announce Dynamic Updates with Live Regions

When content on the screen updates asynchronously (such as a timer countdown, a file upload completion message, or a real-time validation banner), sighted users see the change immediately.

But screen reader users won't know that anything changed unless you mark the changing container as a live region.

Compose provides liveRegion = LiveRegionMode.Polite and liveRegion = LiveRegionMode.Assertive:

• LiveRegionMode.Polite: TalkBack waits until the current audio announcement is finished before reading the update. Use this for almost all status updates.

• LiveRegionMode.Assertive: TalkBack announces the change immediately, ahead of other feedback. Reserve this strictly for time-sensitive, high-urgency alerts (such as emergency warnings).

What to Do (Recommended Practice)

var uploadStatus by remember { mutableStateOf("Ready to upload") }

Text(
    text = uploadStatus,
    modifier = Modifier.semantics {
        liveRegion = LiveRegionMode.Polite
    }
)

// Later, when upload finishes:
LaunchedEffect(Unit) {
    performUpload()
    uploadStatus = "Upload complete! 12 files saved."
}

As soon as uploadStatus changes, TalkBack automatically speaks: "Upload complete! 12 files saved," keeping non-sighted users fully informed without requiring them to search the screen.

How to Support Dynamic Text Scaling

Users with low vision often increase their system font size in Android Settings (under Display or the accessibility settings, depending on the device). Android 14 and newer support non-linear font scaling up to 200%.

To respect this user preference, you must define all text sizes in sp (scale-independent pixels), never in dp or raw pixels.

What to Do (Recommended Practice)

// Good: Using Material Typography (uses sp automatically)
Text(
    text = "Dashboard Summary",
    style = MaterialTheme.typography.titleMedium
)

// Good: Explicit sp sizing
Text(
    text = "Custom Label",
    fontSize = 18.sp
)

When a user sets their font scale to 1.5×, an 18sp font cleanly renders at 27sp, ensuring readable text.

What Not to Do (Antipattern)

// Bad: Fixed dp size converted to sp (does not scale with system settings)
Text(
    text = "Fixed Size Warning",
    fontSize = with(LocalDensity.current) { 16.dp.toSp() } // Will not scale!
)

Sizing text with fixed dp measurements prevents the text from enlarging when users increase their system font size, directly violating accessibility standards.

Advanced Accessibility Techniques

For complex, production-grade applications, you can apply advanced accessibility techniques to handle non-trivial user interactions.

How to Control Traversal and Focus Order

By default, accessibility services traverse screen elements based on their visual and structural coordinates (top-to-bottom, start-to-end). In multi-column layouts, financial ledgers, or custom grids, this default order can create confusing announcements.

You can customize the navigation sequence using traversalIndex and isTraversalGroup:

Column(
    modifier = Modifier.semantics { isTraversalGroup = true }
) {
    Text(
        text = "Step 1: Account Info",
        modifier = Modifier.semantics { traversalIndex = 1f }
    )
    
    Text(
        text = "Step 3: Confirmation",
        modifier = Modifier.semantics { traversalIndex = 3f }
    )
    
    Text(
        text = "Step 2: Payment Details",
        modifier = Modifier.semantics { traversalIndex = 2f }
    )
}

How the code works under the hood:

1. Setting isTraversalGroup = true creates a self-contained accessibility boundary, ensuring TalkBack reads all elements inside this container before moving to other screen elements.

2. The traversalIndex floating-point value establishes the exact relative order (lowest index first). TalkBack will read Step 1, then Step 2, and finally Step 3, regardless of their visual placement in the layout.

How to Create Custom Accessibility Actions

Consider an e-commerce product card that contains "Quick View," "Add to Wishlist," and "Add to Cart" buttons. For a screen reader user, tabbing through three separate buttons on twenty consecutive cards is tedious.

With customActions, you can attach secondary actions directly to the parent card node. When the card gains focus, TalkBack tells the user that actions are available, and the user opens the TalkBack menu to pick one.

var isBookmarked by remember { mutableStateOf(false) }

Card(
    modifier = Modifier
        .fillMaxWidth()
        .semantics {
            customActions = listOf(
                CustomAccessibilityAction(
                    label = if (isBookmarked) "Remove from bookmarks" else "Add to bookmarks",
                    action = {
                        isBookmarked = !isBookmarked
                        true // Return true to indicate the action was handled
                    }
                ),
                CustomAccessibilityAction(
                    label = "Share article link",
                    action = {
                        shareArticle()
                        true
                    }
                )
            )
        }
) {
    // Visual card content...
}

When a TalkBack user focuses on the card, TalkBack informs them that custom actions are available. The user opens the TalkBack menu (or uses accessibility gestures) to see a clean list containing "Add to bookmarks" and "Share article link." This keeps your visual design streamlined while providing direct, high-efficiency navigation for power users.

How to Design Accessible Form Inputs and Text Fields

Accessible form inputs require more than just a visual placeholder. They need explicit labels, clear input type hints, and logical keyboard navigation actions:

var emailValue by remember { mutableStateOf("") }

OutlinedTextField(
    value = emailValue,
    onValueChange = { emailValue = it },
    label = { Text("Work Email") },
    placeholder = { Text("alex@example.com") },
    singleLine = true,
    keyboardOptions = KeyboardOptions(
        keyboardType = KeyboardType.Email,
        imeAction = ImeAction.Next
    ),
    keyboardActions = KeyboardActions(
        onNext = { /* Move focus to password field */ }
    ),
    modifier = Modifier
        .fillMaxWidth()
        .semantics {
            contentDescription = "Work email address input field"
        }
)

How it works under the hood:

• The label composable provides persistent context that remains visible even after the user types.

• keyboardType = KeyboardType.Email instructs Android to display an email-optimized keyboard (including @ and .com shortcuts) and hints to accessibility services that standard email syntax is expected.

• imeAction = ImeAction.Next ensures hardware keyboard users and switch device users can smoothly advance through form fields using the keyboard Enter key.

How to Communicate Dynamic Error States

When client-side validation fails, setting the visual border to red isn't enough. You must attach semantic error metadata so screen readers announce the validation failure immediately.

var password by remember { mutableStateOf("") }
val isPasswordInvalid = password.isNotEmpty() && password.length < 8

OutlinedTextField(
    value = password,
    onValueChange = { password = it },
    label = { Text("Password") },
    isError = isPasswordInvalid,
    supportingText = {
        if (isPasswordInvalid) {
            Text(
                text = "Password must be at least 8 characters long",
                color = MaterialTheme.colorScheme.error
            )
        }
    },
    modifier = Modifier
        .fillMaxWidth()
        .semantics {
            if (isPasswordInvalid) {
                error("Password must be at least 8 characters long")
            }
        }
)

How it works under the hood:

The isError = isPasswordInvalid parameter handles the visual styling (red outline and error icons).

• The error("...") semantic property tells TalkBack to treat this element as invalid and announce the specific validation error message as soon as the user focuses the text field.

How to Manage Progress Indicators and Asynchronous Loading

Loading states must clearly convey whether a task is indeterminate (in progress with unknown duration) or determinate (progressing toward 100%).

// Indeterminate Progress (such as initial network fetch)
CircularProgressIndicator(
    modifier = Modifier.semantics {
        contentDescription = "Syncing messages, please wait"
    }
)

// Determinate Progress (such as file download)
val downloadProgress = 0.65f // 65%

LinearProgressIndicator(
    progress = { downloadProgress },
    modifier = Modifier.semantics {
        progressBarRangeInfo = ProgressBarRangeInfo(
            current = downloadProgress,
            range = 0f..1f
        )
        contentDescription = "Downloading update: ${(downloadProgress * 100).toInt()}% completed"
    }
)

For determinate progress indicators, ProgressBarRangeInfo tells assistive technologies the minimum, maximum, and current values. TalkBack interprets this information and provides periodic spoken and haptic updates as progress increases.

How to Handle Expandable and Collapsible Content

Accordion menus and expandable FAQ cards must clearly indicate whether they're open or closed, and what action tapping them will trigger.

var isExpanded by remember { mutableStateOf(false) }

Column(modifier = Modifier.fillMaxWidth()) {
    Row(
        verticalAlignment = Alignment.CenterVertically,
        modifier = Modifier
            .fillMaxWidth()
            .clickable(
                onClickLabel = if (isExpanded) "Collapse section" else "Expand section"
            ) {
                isExpanded = !isExpanded
            }
            .semantics {
                stateDescription = if (isExpanded) "Expanded" else "Collapsed"
            }
            .padding(16.dp)
    ) {
        Text(
            text = "Frequently Asked Questions",
            style = MaterialTheme.typography.titleMedium,
            modifier = Modifier.weight(1f)
        )
        Icon(
            imageVector = if (isExpanded) Icons.Default.ExpandLess else Icons.Default.ExpandMore,
            contentDescription = null // Decorative: parent Row communicates full state
        )
    }

    AnimatedVisibility(visible = isExpanded) {
        Text(
            text = "Our refund policy allows returns within 30 days of purchase...",
            modifier = Modifier.padding(16.dp)
        )
    }
}

The stateDescription announces whether the section is currently open or closed ("Expanded" or "Collapsed"). Simultaneously, onClickLabel clarifies the upcoming action ("Collapse section" or "Expand section"). The icon has contentDescription = null to avoid redundant announcements.

How to Enhance Lazy Lists and Large Collections

When users navigate a long feed or list, they need context regarding where they are and how many items exist.

val messages = remember { listOf("Order Shipped", "Delivery Delayed", "Payment Received") }

LazyColumn(
    modifier = Modifier.semantics {
        contentDescription = "Notifications list, ${messages.size} total alerts"
    }
) {
    itemsIndexed(messages) { index, messageText ->
        Card(
            modifier = Modifier
                .fillMaxWidth()
                .padding(vertical = 4.dp)
                .semantics {
                    contentDescription = "Notification ${index + 1} of ${messages.size}: $messageText"
                }
        ) {
            Text(
                text = messageText,
                modifier = Modifier.padding(16.dp)
            )
        }
    }
}

TalkBack announces positional indexes ("Notification 1 of 3: Order Shipped"), allowing screen reader users to track their progress through lists without losing their place.

How to Test and Debug Accessibility

Building accessible software requires a multi-layered testing strategy: automated regression checks, on-device diagnostic tools, semantics tree inspection, and manual verification with TalkBack.

How to Test Manually with TalkBack

Nothing replaces manually navigating your application using TalkBack.

How to Enable and Use TalkBack

1. Open your device's Settings app and navigate to Accessibility and then TalkBack.

2. Toggle the switch to On and accept the system permissions. (You can also use the volume key shortcut, if enabled: hold both volume keys for a few seconds to toggle TalkBack).

3. Core TalkBack gestures:

   • Swipe Right: Move accessibility focus to the next element.

   • Swipe Left: Move accessibility focus to the previous element.

   • Double Tap: Activate the currently focused element.

   • Two-Finger Swipe: Scroll lists or pages.

   • Three-Finger Tap (or swipe down then right in one motion): Open the TalkBack menu.

What to check during your TalkBack walkthrough:

• Can you complete critical user journeys (such as registration, login, searching, and checkout) with your eyes closed?

• Are all buttons and interactive controls clearly announced with meaningful names?

• Does focus move in a logical, expected reading order?

• Are error messages and dynamic state changes announced automatically?

How to Write Automated Compose Accessibility Tests

You can integrate automated accessibility assertions into your JUnit instrumented tests to catch missing descriptions and undersized touch targets on continuous integration (CI) servers.

Add Dependencies to build.gradle.kts:

androidTestImplementation("androidx.compose.ui:ui-test-junit4")
androidTestImplementation("androidx.compose.ui:ui-test-manifest")

Writing Compose Accessibility Tests:

@RunWith(AndroidJUnit4::class)
class AccessibilityTest {

    @get:Rule
    val composeTestRule = createAndroidComposeRule<ComponentActivity>()

    @Test
    fun testLoginButton_hasProperTouchTargetAndLabel() {
        composeTestRule.setContent {
            MaterialTheme {
                Button(
                    onClick = { /* Submit login */ },
                    modifier = Modifier.minimumInteractiveComponentSize()
                ) {
                    Text("Sign In")
                }
            }
        }

        // Verify the node exists with correct text and semantics
        composeTestRule
            .onNodeWithText("Sign In")
            .assertExists()
            .assertHasClickAction()
            .assertHeightIsAtLeast(48.dp)
            .assertWidthIsAtLeast(48.dp)
    }

    @Test
    fun testIconButton_containsContentDescription() {
        composeTestRule.setContent {
            MaterialTheme {
                IconButton(onClick = {}) {
                    Icon(
                        imageVector = Icons.Default.Favorite,
                        contentDescription = "Add to favorites"
                    )
                }
            }
        }

        // Verify content description is accurately exposed in semantics tree
        composeTestRule
            .onNode(hasContentDescription("Add to favorites"))
            .assertExists()
            .assertHasClickAction()
    }
}

Step-by-Step Guide to Google Accessibility Scanner

Google Accessibility Scanner is an Android diagnostic tool that inspects your app's rendered UI and flags accessibility violations.

How to Install and Set Up Accessibility Scanner

1. Install from Google Play: Open the Google Play Store on your test device and install Accessibility Scanner (published by Google LLC).

2. Enable in Accessibility Settings:

   • Go to Settings then Accessibility and then Accessibility Scanner.

   • Toggle the switch to On and grant the required screen-reading permissions.

3. Locate the Floating Button: A blue floating action button with a checkmark icon (✓) will appear overlaid on your screen.

Running a Scan and Interpreting Results

Open your Android application and navigate to the screen you want to audit. Tap the floating blue Scanner button.

Then tap the Snapshot (camera) icon to analyze the static screen, or tap Record to audit a multi-step user flow.

The Scanner outlines each flagged UI component with an orange rectangle. Typical findings include interactive touch targets smaller than 48dp, missing labels on buttons and images, insufficient text or image contrast, and duplicate or redundant descriptions.

Tap any highlighted result to view a detailed breakdown explaining the problem, a link to the relevant accessibility guidance, and suggested remediation steps. Keep in mind that Scanner is a diagnostic aid. A clean scan doesn't guarantee that your app is fully accessible.

Figure: Google Accessibility Scanner auditing the AccessibilityDemo app, flagging an undersized 24dp touch target and displaying remediation guidance.

How to Inspect Semantics with Android Studio Layout Inspector

Android Studio's Layout Inspector allows you to inspect your running Compose hierarchy in real time and view the exact Semantics Tree exposed to the operating system.

How to Inspect Semantics Step-by-Step

1. Run your Compose application on an emulator or physical device connected via USB debugging.

2. In Android Studio, open View then Tool Windows and then Layout Inspector.

3. In the process selector dropdown, select your application's process (such as com.example.accessibilitydemo).

4. In the Layout Inspector component tree panel on the left, navigate to the composable you want to inspect (such as the Card under Semantic Merging).

5. Look at the Attributes panel on the right. You'll see dedicated sections for:

   • Merged Semantics: Displays the collapsed semantic metadata exposed to accessibility services when mergeDescendants = true is used (including merged ContentDescription, Text lists, OnClick actions, and container flags).

   • Declared Semantics: Shows the explicit semantic properties directly attached to that specific composable node.

Figure: Android Studio Layout Inspector inspecting the AccessibilityDemo app, displaying the Component Tree on the left, visual wireframes in the center, and the Merged Semantics attributes panel on the right.

Using Layout Inspector provides visual confirmation that:

• semantics(mergeDescendants = true) is properly grouping disparate children into a single node.

• Decorative icons are successfully excluded from the accessibility tree.

• Click actions (OnClick: AccessibilityAction) and custom actions are correctly wired to the composable.

Real-World Accessible UI Patterns

Here are complete, production-ready implementations of common UI patterns:

Fully Accessible Login Form

Forms are critical entry points. This implementation combines heading semantics, email input validation, dynamic error announcements, and proper touch target sizing:

@Composable
fun AccessibleLoginForm(
    onLoginSubmitted: (String, String) -> Unit
) {
    var email by remember { mutableStateOf("") }
    var password by remember { mutableStateOf("") }
    var isSubmitted by remember { mutableStateOf(false) }

    val isEmailInvalid = isSubmitted && !android.util.Patterns.EMAIL_ADDRESS.matcher(email).matches()
    val isPasswordInvalid = isSubmitted && password.length < 8

    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(24.dp)
    ) {
        // 1. Designated Screen Title Heading
        Text(
            text = "Welcome Back",
            style = MaterialTheme.typography.headlineLarge,
            modifier = Modifier.semantics { heading() }
        )

        Text(
            text = "Sign in to access your account",
            style = MaterialTheme.typography.bodyMedium,
            color = MaterialTheme.colorScheme.onSurfaceVariant
        )

        Spacer(modifier = Modifier.height(24.dp))

        // 2. Accessible Email Input
        OutlinedTextField(
            value = email,
            onValueChange = { email = it },
            label = { Text("Email Address") },
            isError = isEmailInvalid,
            singleLine = true,
            keyboardOptions = KeyboardOptions(
                keyboardType = KeyboardType.Email,
                imeAction = ImeAction.Next
            ),
            supportingText = {
                if (isEmailInvalid) {
                    Text(
                        text = "Please enter a valid email address",
                        color = MaterialTheme.colorScheme.error
                    )
                }
            },
            modifier = Modifier
                .fillMaxWidth()
                .semantics {
                    if (isEmailInvalid) {
                        error("Please enter a valid email address")
                    }
                }
        )

        Spacer(modifier = Modifier.height(16.dp))

        // 3. Accessible Password Input
        OutlinedTextField(
            value = password,
            onValueChange = { password = it },
            label = { Text("Password") },
            isError = isPasswordInvalid,
            singleLine = true,
            visualTransformation = PasswordVisualTransformation(),
            keyboardOptions = KeyboardOptions(
                keyboardType = KeyboardType.Password,
                imeAction = ImeAction.Done
            ),
            supportingText = {
                if (isPasswordInvalid) {
                    Text(
                        text = "Password must be at least 8 characters long",
                        color = MaterialTheme.colorScheme.error
                    )
                }
            },
            modifier = Modifier
                .fillMaxWidth()
                .semantics {
                    if (isPasswordInvalid) {
                        error("Password must be at least 8 characters long")
                    }
                }
        )

        Spacer(modifier = Modifier.height(24.dp))

        // 4. Accessible Submit Button
        Button(
            onClick = {
                isSubmitted = true
                if (!isEmailInvalid && !isPasswordInvalid) {
                    onLoginSubmitted(email, password)
                }
            },
            modifier = Modifier
                .fillMaxWidth()
                .minimumInteractiveComponentSize()
                .semantics {
                    contentDescription = "Sign in to your account"
                }
        ) {
            Text("Sign In")
        }
    }
}

Why this pattern works:

1. Screen Heading: TalkBack users can instantly jump to "Welcome Back" when entering the screen.

2. Error Semantics: If validation fails, error("...") ensures TalkBack immediately speaks the validation requirement when the text field receives focus.

3. Keyboard Routing: ImeAction.Next and ImeAction.Done guide keyboard and switch users smoothly between input fields.

E-Commerce Product Card with Custom Actions

This pattern demonstrates how to combine mergeDescendants = true with customActions to create a concise, power-user-friendly card:

data class Product(
    val id: String,
    val title: String,
    val priceFormatted: String,
    val rating: Float,
    val imageRes: Int
)

@Composable
fun AccessibleProductCard(
    product: Product,
    onCardClick: () -> Unit,
    onToggleFavorite: () -> Unit,
    onAddToCart: () -> Unit
) {
    Card(
        modifier = Modifier
            .fillMaxWidth()
            .clickable(onClickLabel = "View product details") { onCardClick() }
            .semantics(mergeDescendants = true) {
                // Group all descriptive properties into one coherent announcement
                contentDescription = "${product.title}, Price: ${product.priceFormatted}, Rated ${product.rating} out of 5 stars"
                
                // Expose secondary operations as custom accessibility actions
                customActions = listOf(
                    CustomAccessibilityAction("Add to shopping cart") {
                        onAddToCart()
                        true
                    },
                    CustomAccessibilityAction("Save to favorites") {
                        onToggleFavorite()
                        true
                    }
                )
            }
    ) {
        Row(
            modifier = Modifier.padding(16.dp),
            verticalAlignment = Alignment.CenterVertically
        ) {
            Image(
                painter = painterResource(product.imageRes),
                contentDescription = null, // Decorative: covered by merged description
                modifier = Modifier
                    .size(80.dp)
                    .clip(RoundedCornerShape(8.dp))
            )

            Spacer(modifier = Modifier.width(16.dp))

            Column(modifier = Modifier.weight(1f)) {
                Text(
                    text = product.title,
                    style = MaterialTheme.typography.titleMedium
                )
                Text(
                    text = product.priceFormatted,
                    style = MaterialTheme.typography.bodyLarge,
                    fontWeight = FontWeight.Bold
                )
                Text(
                    text = "★ ${product.rating}",
                    style = MaterialTheme.typography.bodySmall,
                    color = MaterialTheme.colorScheme.onSurfaceVariant
                )
            }
        }
    }
}

Why this pattern works:

1. Single Semantic Stop: Instead of swiping four times through separate image and text views, TalkBack reads the entire card in one unified statement.

2. Action Shortcuts: Users can add items to their cart or favorites directly from the TalkBack actions menu without navigating into the details page.

Tab Navigation with Selection State

This pattern demonstrates accessible tab bar navigation using stateDescription and custom tab announcements:

@Composable
fun AccessibleTabNavigation(
    tabs: List<String>,
    selectedTabIndex: Int,
    onTabSelected: (Int) -> Unit
) {
    TabRow(
        selectedTabIndex = selectedTabIndex,
        modifier = Modifier.semantics {
            contentDescription = "Navigation tabs, ${tabs[selectedTabIndex]} selected"
        }
    ) {
        tabs.forEachIndexed { index, title ->
            val isSelected = selectedTabIndex == index
            Tab(
                selected = isSelected,
                onClick = { onTabSelected(index) },
                modifier = Modifier.semantics {
                    role = Role.Tab
                    stateDescription = if (isSelected) "Selected" else "Not selected"
                    contentDescription = "$title tab"
                }
            ) {
                Text(
                    text = title,
                    modifier = Modifier.padding(vertical = 16.dp)
                )
            }
        }
    }
}

Why this pattern works:

1. Explicit Role: Marking each item with Role.Tab informs accessibility services that this is a selectable tab container.

2. Selection Feedback: The stateDescription tells the user whether a tab is currently active before they tap it.

Confirmation Dialog with Action Descriptions

This pattern shows how to structure an accessible confirmation dialog:

@Composable
fun AccessibleDeleteConfirmationDialog(
    itemName: String,
    onDismissRequest: () -> Unit,
    onConfirmDelete: () -> Unit
) {
    AlertDialog(
        onDismissRequest = onDismissRequest,
        title = {
            Text(
                text = "Delete Item?",
                style = MaterialTheme.typography.headlineSmall,
                modifier = Modifier.semantics { heading() }
            )
        },
        text = {
            Text("Are you sure you want to permanently delete \"$itemName\"? This action cannot be undone.")
        },
        confirmButton = {
            TextButton(
                onClick = onConfirmDelete,
                modifier = Modifier.semantics {
                    contentDescription = "Confirm deletion of $itemName"
                }
            ) {
                Text("Delete", color = MaterialTheme.colorScheme.error)
            }
        },
        dismissButton = {
            TextButton(
                onClick = onDismissRequest,
                modifier = Modifier.semantics {
                    contentDescription = "Cancel deletion and close dialog"
                }
            ) {
                Text("Cancel")
            }
        },
        modifier = Modifier.semantics {
            contentDescription = "Delete item confirmation dialog"
        }
    )
}

Why this pattern works:

1. Clear Focus: When the dialog appears, TalkBack automatically traps focus within the dialog bounds so users can't accidentally click background elements.

2. Context-Rich Buttons: Button descriptions explain the exact consequence of clicking ("Confirm deletion of Shopping List" rather than just "Delete").

Accessibility Audit Checklist

Before releasing your app to production or submitting it to app stores, run through this accessibility audit checklist:

Visual and Typography

• Scalable Text: Define all font sizes in sp (never fixed dp) so text scales cleanly up to 200%.

• Color Contrast: Maintain at least a 4.5:1 contrast ratio for normal text and 3.0:1 for large text and essential UI components against their backgrounds.

• Color Independence: Never convey information through color alone. Always pair color cues with text labels or distinct icons.

Interactive Elements and Touch Targets

• Touch Target Sizing: Ensure every clickable or interactive component has a minimum hit target of 48dp × 48dp using Modifier.minimumInteractiveComponentSize().

• Actionable Descriptions: Provide descriptive, action-oriented contentDescription strings on all functional icon buttons and interactive images.

• Decorative Elements: Set contentDescription = null on purely decorative icons and illustrations to keep TalkBack feedback concise.

• Click Context: Provide custom onClickLabel parameters on cards, list items, and custom buttons to clarify the outcome before activation.

Screen Structure and Navigation

• Accessibility Headings: Mark major section titles and screen headers with Modifier.semantics { heading() } for rapid heading navigation.

• Semantic Merging: Group related visual sub-elements (such as ratings or multi-text card headers) using Modifier.semantics(mergeDescendants = true).

• Live Announcements: Designate asynchronous UI updates with liveRegion = LiveRegionMode.Polite so TalkBack announces background changes.

• Form Optimization: Specify appropriate keyboardType and imeAction configurations on all text inputs.

• Validation Feedback: Declare active input error states using Modifier.semantics { error("...") }.

Testing and Verification

• Automated Unit Tests: Add Compose accessibility assertions in continuous integration to catch touch target and missing label regressions.

• On-Device Diagnostic Audit: Run Google Accessibility Scanner across all key app screens to catch contrast or sizing defects.

• Semantics Tree Inspection: Use Android Studio Layout Inspector to verify merged semantics and declared accessibility actions.

• Manual Screen Reader Walkthrough: Complete end-to-end user journeys (login, checkout, navigation) with TalkBack enabled.

Conclusion and Next Steps

Building accessible applications in Jetpack Compose doesn't mean just retrofitting code at the end of a project. You need to understand Compose's dual-tree architecture and design your user interface so that both visual pixels and semantic metadata accurately represent your application's intent.

By applying semantic properties, ensuring 48dp touch targets, maintaining WCAG contrast ratios, and verifying your work with TalkBack and Google Accessibility Scanner, you ensure that your Android applications are welcoming, compliant, and intuitive for all users worldwide.

Essential Resources

To deepen your understanding of Android accessibility, consult these essential references:

• Android Developers Official Guide: Accessibility in Jetpack Compose

• Android Developers Official Guide: Semantics in Compose

• W3C Web Content Accessibility Guidelines (WCAG) 2.1 Quick Reference

• Google Material Design 3: Accessible Design Foundations

At the time, there was no built-in composable to display tooltips and there were several alternative solutions circling online. The problem with those solutions was that once Jetpack Compose released newer versions, those solutions might break. So it wasn’t ideal and the community was left hoping that sometime in the future, support would be added for tooltips.

I’m glad to say that since version 1.1.0 of Compose Material 3, we now have built in tooltip support. 👏

While this in itself is great, more than a year has passed since that version was released. And with subsequent versions, the API related to tooltips changed drastically as well.

If you go over the changelog, you will see how the public and internal APIs have changed. So bear in mind, that when you read this article, things may have continued to change as everything related to Tooltips is still marked by the annotation ExperimentalMaterial3Api::class.

❗️ The version of material 3 used for this article is 1.2.1, which was released on March 6th, 2024

Tooltip Types

We now have support for two different types of tooltips:

1. Plain tooltip

2. Rich media tooltip

Plain Tooltip

You can use the first kind to provide information about an icon button that wouldn’t be clear otherwise. For example, you can use a plain tooltip to indicate to a user what the icon button represents.

To add a tooltip to your application, you use the TooltipBox composable. This composable takes several arguments:

fun TooltipBox(
    positionProvider: PopupPositionProvider,
    tooltip: @Composable TooltipScope.() -> Unit,
    state: TooltipState,
    modifier: Modifier = Modifier,
    focusable: Boolean = true,
    enableUserInput: Boolean = true,
    content: @Composable () -> Unit,
)

Some of these should be familiar to you if you have used Composables before. I’ll highlight the ones that have a specific use case here:

• positionProvider - Of PopupPositionProvider type, and is used to calculate the position of the tooltip.

• tooltip - This is where you can design the UI of how the tooltip will look like.

• state - This holds the state that is associated with a specific Tooltip instance. It exposes methods like showing/dismissing the tooltip and when instantiating an instance of one, you can declare if the tooltip should be persistent or not (meaning if it should keep displaying on the screen until a user performs a click action outside the tooltip).

• content - This is the UI that the tooltip will display above/below.

Here is an example of instantiating a BasicTooltipBox with all the relevant arguments filled in:

@OptIn(ExperimentalFoundationApi::class, ExperimentalMaterial3Api::class)
@Composable
fun BasicTooltip() {
    val tooltipPosition = TooltipDefaults.rememberPlainTooltipPositionProvider()
    val tooltipState = rememberBasicTooltipState(isPersistent = false)

    BasicTooltipBox(positionProvider = tooltipPosition,
        tooltip =  { Text("Hello World") } ,
        state = tooltipState) {
        IconButton(onClick = { }) {
            Icon(imageVector = Icons.Filled.Favorite, 
                 contentDescription = "Your icon's description")
        }
    }
}

Jetpack Compose has a built in class called TooltipDefaults. You can use this class to help you instantiate arguments that make up a TooltipBox. For instance, you could use TooltipDefaults.rememberPlainTooltipPositionProvider to correctly position the tooltip in relation to the anchor element.

Rich Tooltip

A rich media tooltip takes more space than a plain tooltip and can be used to provide more context about the functionality of an icon button. When the tooltip is shown, you can add buttons and links to it to provide further explanation or definitions.

It is instantiated in a similar way as a plain tooltip, inside of a TooltipBox, but you use the RichTooltip composable.

TooltipBox(positionProvider = tooltipPosition,
        tooltip = {
                  RichTooltip(
                      title = { Text("RichTooltip") },
                      caretSize = caretSize,
                      action = {
                          TextButton(onClick = {
                              scope.launch {
                                  tooltipState.dismiss()
                                  tooltipState.onDispose()
                              }
                          }) {
                              Text("Dismiss")
                          }
                      }
                  ) {
                        Text("This is where a description would go.")
                  }
        },
        state = tooltipState) {
        IconButton(onClick = {
            /* Icon button's click event */
        }) {
            Icon(imageVector = tooltipIcon,
                contentDescription = "Your icon's description",
                tint = iconColor)
        }
    }

A few things to notice about a Rich tooltip:

1. A Rich tooltip has support for a caret.

2. You can add an action (that is, a button) to the tooltip to give users an option to find out more information.

3. You can add logic to dismiss the tooltip.

Edge Cases

When you choose to mark your tooltip state as persistent, it means that once the user interacts with the UI that shows your tooltip, it will stay visible until the user presses anywhere else on the screen.

If you looked at the example of a Rich tooltip from above, you might have noticed that we have added a button to dismiss the tooltip once it’s clicked.

There is a problem that happens once a user presses that button. Since the dismiss action is performed on the tooltip, if a user wants to perform another long press on the UI item that invokes this tooltip, the tooltip won’t be shown again. This means that the state of the tooltip is persistent on it being dismissed. So, how do we go about and resolve this?

In order to “reset” the state of the tooltip, we have to call the onDispose method that is exposed through the tooltip state. Once we do that, the tooltip state is reset and the tooltip will be shown again when the user performs a long press on the UI item.

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun RichTooltip() {
    val tooltipPosition = TooltipDefaults.rememberRichTooltipPositionProvider()
    val tooltipState = rememberTooltipState(isPersistent = true)
    val scope = rememberCoroutineScope()

    TooltipBox(positionProvider = tooltipPosition,
        tooltip = {
                  RichTooltip(
                      title = { Text("RichTooltip") },
                      caretSize = TooltipDefaults.caretSize,
                      action = {
                          TextButton(onClick = {
                              scope.launch {
                                  tooltipState.dismiss()
                                  tooltipState.onDispose()  /// <---- HERE
                              }
                          }) {
                              Text("Dismiss")
                          }
                      }
                  ) {

                  }
        },
        state = tooltipState) {
        IconButton(onClick = {  }) {
            Icon(imageVector = Icons.Filled.Call, contentDescription = "Your icon's description")
        }
    }
}

Another scenario where the tooltip state does not reset is if instead of calling ourselves for the dismiss method per a user’s action, the user clicks outside of the tooltip, causing it to be dismissed. This calls the dismiss method behind the scenes and the tooltip state is set to dismissed. Long pressing on the UI element to see our tooltip again will result in nothing.

Our logic that calls the tooltip’s onDispose method does not get triggered, so how can we reset the tooltip’s state?

Currently, I haven’t been able to figure this out. It might be related to the tooltip’s MutatorMutex. Maybe with upcoming releases, there will be an API for this. I did notice that if other tooltips are present on the screen and they are pressed, this resets the previously clicked upon tooltip.

If you would like to see the code featured here, you can go to this GitHub repository

If you would like to see tooltips in an application, you can check it out here.

References

• Material3 Tooltip Overview

• Tooltip Defaults

• Tooltip Source Code

If your application depends on getting the user’s location, you want to ensure that the user has a good experience when the application requests this info. So it's crucial to handle all the edge cases and allow the user to select the option the they're most comfortable with.

With Jetpack Compose, the logic associated with getting the user’s location has changed a bit, and it’s important to know the in’s and out’s of how it can be done.

As with most things, there is a library you can use to handle getting permissions. It’s from Accompanist (read Google) and you can find it here. But you are here to learn how to do things yourself, right? So read on. 🕵️‍♀️

Before we get into the code and the logic, it is important to understand that requesting a permission from a user is a path that can have many decision points. As such, it is best described by having states that represent the current status of the permission (approved/rejected/denied) and the current status of the operating system.

The diagram below illustrates this flow:

Later on in this article, you will see how we will represent these states in variables in our code.

Save Our Souls (S.O.S)

Before we get to the logic of asking for a permission, we’ll take care of the boilerplate around it. As always, add the necessary permissions to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Then, we’ll create a composable screen where we ask for the necessary location permissions. The first step in this screen is to check whether the user has previously granted the required permissions. You can do this with something that is not new to Jetpack Compose – using the checkSelfPermission method:

val locationPermissionsAlreadyGranted = ContextCompat.checkSelfPermission(
            this,
            Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED

If the permission is not granted, we have to request it. We will use the rememberLauncherForActivityResult object to do this. This allows us in Jetpack Compose to get a result from an Activity.

val locationPermissions = arrayOf(
    Manifest.permission.ACCESS_FINE_LOCATION,
    Manifest.permission.ACCESS_COARSE_LOCATION)

val locationPermissionLauncher = rememberLauncherForActivityResult(
                contract = ActivityResultContracts.RequestMultiplePermissions(),
                onResult = { permissions ->
                    val permissionsGranted = permissions.values.reduce { acc, isPermissionGranted ->
                        acc && isPermissionGranted
                    }

                    if (!permissionsGranted) {
                       //Logic when the permissions were not granted by the user
                    }
                })

The arguments that we need to pass to rememberLauncherForActivityResult are:

1. An ActivityResultContract – specifies the input of the activity and the output
2. onResult – a callback when the result is received

In the code snippet above, we are using a multiple permissions contract, since we are requesting several location permissions. There is also a contract for requesting just one permission, ActivityResultContracts.RequestPermission().

This piece of code doesn’t not run immediately as we need to request the permissions. To do that we use the launch method to start the activity:

locationPermissionLauncher.launch(locationPermissions)

In the case the user gave all or several of the required permissions, we can continue the logic of the application.

But, if the user did not approve any of the permissions, we need to find a way to make the user understand why these permissions are necessary.

Explaining the Rationale

In case the user declined the permission, but did not select the “Deny And Don’t Ask Me Again” option, we have a way of giving the user a brief explanation on why they should grant the required permission(s).

To figure out if we should present this rationale, we use the shouldShowRequestPermissionRationale from the Activity class:

val shouldShowPermissionRationale: Boolean = shouldShowRequestPermissionRationale(Manifest.permission.ACCESS_COARSE_LOCATION)

Once we know that we can display this explanation, there are two ways to go about it:

1. We can present it to the user with an AlertDialog
2. We can use the Snackbar

Presenting an alert dialog is pretty straightforward. All we have to do is make sure we describe clearly to the user why it is required to approve this permission:

@Composable
    fun ShowLocationPermissionRationale() {
        AlertDialog(
            onDismissRequest = {
               //Logic when dismiss happens
            },
        title = {
            Text("Permission Required")
                },
        text = {
            Text("You need to approve this permission in order to...")
        },
        confirmButton = {
            TextButton(onClick = {
              //Logic when user confirms to accept permissions
            }) {
                Text("Confirm")
            }
        },
        dismissButton = {
            TextButton(onClick = {
              //Logic when user denies to accept permissions
            }) {
                Text("Deny")
            }
        })
    }

If we want to present the Snackbar, we need to be aware that we have to use a Scaffold container since that is the only container that supports showing a Snackbar. If we don’t use one, a Snackbar won’t appear.

Below is a snippet that shows you how to do this:

val scope = rememberCoroutineScope()
val snackbarHostState = remember { SnackbarHostState() }

Scaffold(snackbarHost = {
        SnackbarHost(hostState = snackbarHostState)
    }) { contentPadding ->
        if (shouldShowPermissionRationale) {
            LaunchedEffect(key1 = shouldShowPermissionRationale, block = {
                scope.launch {
                    val userAction = snackbarHostState.showSnackbar(
                        message ="Please authorize location permissions",
                        actionLabel = "Approve",
                        duration = SnackbarDuration.Indefinite,
                        withDismissAction = true
                    )
                    when (userAction) {
                        SnackbarResult.ActionPerformed -> {
                            //User approved to grant the permission
                            //Ask for permissions again
                        }
                        SnackbarResult.Dismissed -> {
                            //User dismissed snackbar
                        }
                    }
                }
            })
        }
}

We allowed the Snackbar itself to be dismissible using the withDismissAction attribute and listened in to the action performed by the user.

Lifecycle Observer

One thing we have glossed over is the fact that we need to make sure our permission request adheres to the composable lifecycle. This means that once a user chooses their preferences regarding the permission request, we need the UI to adapt accordingly.

If you try and put the code above inside the activity’s onCreate method, you will be surprised with the outcome, since the application will crash with the following exception:

java.lang.IllegalStateException: Launcher has not been initialized

This is because Composable functions are supposed to be side effect free. What is a side effect? According to Google’s documentation it is:

… a change to the state of the app that happens outside the scope of a composable function

So, in our use case, launching an activity for the permissions is the side effect happening here.

To circumvent this scenario, we need to use one of the side effect options. Since we don’t want to ask the user for permissions without remembering what their choices were previously, we can’t use the general SideEffect. And LaunchedEffect is used for calling suspend methods inside of a Composable, which is not our use case here.

So we are left with DisposableEffect. Reading the documentation, we can see that DisposableEffect can be combined with Lifecycle events, which is what we are after.

val lifecycleOwner = LocalLifecycleOwner.current
            DisposableEffect(key1 = lifecycleOwner, effect = {
                val observer = LifecycleEventObserver { _, event ->
                    if (event == Lifecycle.Event.ON_START && !locationPermissionsAlreadyGranted) {
                        locationPermissionLauncher.launch(locationPermissions)
                       }
                    }
                    lifecycleOwner.lifecycle.addObserver(observer)
                    onDispose {
                        lifecycleOwner.lifecycle.removeObserver(observer)
                    }
                }
            )

In the code snippet above, we are adding a lifecycle observer that runs only in the case of the onStart lifecycle event. We also combine it with the boolean we have declared at the start of this section, locationPermissionsAlreadyGranted. This is so we won’t show the dialog for asking permissions if they are already granted.

As with all lifecycle observers, we need to remove our observer once the composition ends. We have that logic inside DisposableEffect’s onDispose clause.

Location Not Found

The last case we need to deal with is when the user chooses the “Deny And Don’t Ask Me Again” option. When this happens, we cannot ask the user to grant the required permissions.

The only way the user can revert their choice is to go to the settings screen of our application and change the permissions there. So we need to direct the user to go there.

To open the settings screen of our application, we need to use an intent with the action of ACTION_APPLICATION_DETAILS_SETTINGS.

Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.fromParts("package", packageName, null)).also {
            startActivity(it)
        }

Taking the logic above, we can add it to our code when we know that the user has chosen to deny the permissions and not be asked again. This happens inside our request for permissions when the user has not granted the permissions and the option to show the rationale is false.

Location Confirmed

If we take everything we discussed in this article and put it inside one file, we will get the following code:

class MainActivity : ComponentActivity() {

    @OptIn(ExperimentalMaterial3Api::class)
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {

            var locationPermissionsGranted by remember { mutableStateOf(areLocationPermissionsAlreadyGranted()) }
            var shouldShowPermissionRationale by remember {
                mutableStateOf(
                    shouldShowRequestPermissionRationale(Manifest.permission.ACCESS_COARSE_LOCATION)
                )
            }

            var shouldDirectUserToApplicationSettings by remember {
                mutableStateOf(false)
            }

            var currentPermissionsStatus by remember {
                mutableStateOf(decideCurrentPermissionStatus(locationPermissionsGranted, shouldShowPermissionRationale))
            }

            val locationPermissions = arrayOf(
                Manifest.permission.ACCESS_FINE_LOCATION,
                Manifest.permission.ACCESS_COARSE_LOCATION
            )

            val locationPermissionLauncher = rememberLauncherForActivityResult(
                contract = ActivityResultContracts.RequestMultiplePermissions(),
                onResult = { permissions ->
                    locationPermissionsGranted = permissions.values.reduce { acc, isPermissionGranted ->
                        acc && isPermissionGranted
                    }

                    if (!locationPermissionsGranted) {
                        shouldShowPermissionRationale =
                            shouldShowRequestPermissionRationale(Manifest.permission.ACCESS_COARSE_LOCATION)
                    }
                    shouldDirectUserToApplicationSettings = !shouldShowPermissionRationale && !locationPermissionsGranted
                    currentPermissionsStatus = decideCurrentPermissionStatus(locationPermissionsGranted, shouldShowPermissionRationale)
                })

            val lifecycleOwner = LocalLifecycleOwner.current
            DisposableEffect(key1 = lifecycleOwner, effect = {
                val observer = LifecycleEventObserver { _, event ->
                    if (event == Lifecycle.Event.ON_START &&
                        !locationPermissionsGranted &&
                        !shouldShowPermissionRationale) {
                        locationPermissionLauncher.launch(locationPermissions)
                    }
                }
                lifecycleOwner.lifecycle.addObserver(observer)
                onDispose {
                    lifecycleOwner.lifecycle.removeObserver(observer)
                    }
                }
            )

            val scope = rememberCoroutineScope()
            val snackbarHostState = remember { SnackbarHostState() }

            LocationPermissionsTheme {
                Surface(
                    modifier = Modifier.fillMaxSize(),
                    color = MaterialTheme.colorScheme.background
                ) {
                    Scaffold(snackbarHost = {
                        SnackbarHost(hostState = snackbarHostState)
                    }) { contentPadding ->
                        Column(modifier = Modifier.fillMaxSize(),
                        verticalArrangement = Arrangement.Center,
                        horizontalAlignment = Alignment.CenterHorizontally){
                            Text(modifier = Modifier
                                .padding(contentPadding)
                                .fillMaxWidth(),
                                text = "Location Permissions",
                                textAlign = TextAlign.Center)
                            Spacer(modifier = Modifier.padding(20.dp))
                            Text(modifier = Modifier
                                .padding(contentPadding)
                                .fillMaxWidth(),
                                text = "Current Permission Status: $currentPermissionsStatus",
                                textAlign = TextAlign.Center,
                                fontWeight = FontWeight.Bold
                            )
                        }
                        if (shouldShowPermissionRationale) {
                            LaunchedEffect(Unit) {
                                scope.launch {
                                    val userAction = snackbarHostState.showSnackbar(
                                        message ="Please authorize location permissions",
                                        actionLabel = "Approve",
                                        duration = SnackbarDuration.Indefinite,
                                        withDismissAction = true
                                    )
                                    when (userAction) {
                                        SnackbarResult.ActionPerformed -> {
                                            shouldShowPermissionRationale = false
                                            locationPermissionLauncher.launch(locationPermissions)
                                        }
                                        SnackbarResult.Dismissed -> {
                                            shouldShowPermissionRationale = false
                                        }
                                    }
                                }
                            }
                        }
                        if (shouldDirectUserToApplicationSettings) {
                            openApplicationSettings()
                        }
                    }
                }
            }
        }
    }

    private fun areLocationPermissionsAlreadyGranted(): Boolean {
        return ContextCompat.checkSelfPermission(
            this,
            Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED
    }

    private fun openApplicationSettings() {
        Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.fromParts("package", packageName, null)).also {
            startActivity(it)
        }
    }

    private fun decideCurrentPermissionStatus(locationPermissionsGranted: Boolean,
                                              shouldShowPermissionRationale: Boolean): String {
        return if (locationPermissionsGranted) "Granted"
        else if (shouldShowPermissionRationale) "Rejected"
        else "Denied"
    }
}

And this is how it looks like:

I have put all the logic in one file just for the purpose of this article. It is by no means the most esthetic and correct approach to handling the logic with requesting permissions.

You could easily refactor out the logic variables associated with holding the different state of the request for permissions to a view model class that is attached to this screen.

You can see all of the code described in this article by going to this project:

And if you would like to read more of my articles, you can go view them below:

I have also used this logic in an application that you can try out here.

Thank you for reading!

We’ve all done it.

Ain’t nothing like good ol’ tabs to organize content in a complex application. So how do we go about creating a tab layout in Jetpack Compose?

In this tutorial, we’ll go over all of the basics, but also show some things that are more advanced.

How to Create Simple Tabs

To create a tab layout, you need to start with a TabRow. This will be a container element that will hold your tabs.

@Composable
@UiComposable
fun TabRow(
    selectedTabIndex: Int,
    modifier: Modifier = Modifier,
    backgroundColor: Color = MaterialTheme.colors.primarySurface,
    contentColor: Color = contentColorFor(backgroundColor),
    indicator: @Composable @UiComposable (tabPositions: List<TabPosition>) -> Unit = @Composable { tabPositions ->
            TabRowDefaults.Indicator(
                Modifier.tabIndicatorOffset(tabPositions[selectedTabIndex])
            )
        },
    divider: @Composable @UiComposable () -> Unit = @Composable {
            TabRowDefaults.Divider()
        },
    tabs: @Composable @UiComposable () -> Unit
): Unit

• selectedTabIndex indicates the index of the tab that is currently selected
• indicator represents the UI that indicates which tab is currently selected
• divider is a composable that is drawn at the bottom of the TabRow under the indicator
• If you don’t have a need to custom style your tabs, you can use TabRowDefaults as it contains the default values and implementation used for TabRow (you can see it being used inside divider)

Let’s see the usage of TabRow with an example. We will create a simple layout that will have three tabs:

1. Home
2. About
3. Settings

@Composable
fun TabScreen() {
    var tabIndex by remember { mutableStateOf(0) }

    val tabs = listOf("Home", "About", "Settings")

    Column(modifier = Modifier.fillMaxWidth()) {
        TabRow(selectedTabIndex = tabIndex) {
            tabs.forEachIndexed { index, title ->
                Tab(text = { Text(title) },
                    selected = tabIndex == index,
                    onClick = { tabIndex = index }
                )
            }
        }
        when (tabIndex) {
            0 -> HomeScreen()
            1 -> AboutScreen()
            2 -> SettingsScreen()
        }
    }
}

A couple things to pay attention to:

• The TabRow composable holds inside of itself a Tab composable
• After the TabRow composable, we have a when clause to handle what happens when each tab is clicked (in our specific case we are opening different screens)
• We are using a variable called tabIndex to keep track of which Tab is selected

Pretty bland, right?

Let’s spice things up with icons by using the icon attribute of the Tab composable.

@Composable
fun TabScreen() {
    var tabIndex by remember { mutableStateOf(0) }

    val tabs = listOf("Home", "About", "Settings")

    Column(modifier = Modifier.fillMaxWidth()) {
        TabRow(selectedTabIndex = tabIndex) {
            tabs.forEachIndexed { index, title ->
                Tab(text = { Text(title) },
                    selected = tabIndex == index,
                    onClick = { tabIndex = index },
                    icon = {
                        when (index) {
                            0 -> Icon(imageVector = Icons.Default.Home, contentDescription = null)
                            1 -> Icon(imageVector = Icons.Default.Info, contentDescription = null)
                            2 -> Icon(imageVector = Icons.Default.Settings, contentDescription = null)
                        }
                    }
                )
            }
        }
        when (tabIndex) {
            0 -> HomeScreen()
            1 -> AboutScreen()
            2 -> SettingsScreen()
        }
    }
}

Looking better, but a question does arise: What if we have more tabs than the screen can show?

Luckily, the answer is simple.

There is an option to make our TabRow scrollable. Instead of using the TabRow element, you can use the ScrollableTabRow composable.

@Composable
@UiComposable
fun ScrollableTabRow(
    selectedTabIndex: Int,
    modifier: Modifier = Modifier,
    backgroundColor: Color = MaterialTheme.colors.primarySurface,
    contentColor: Color = contentColorFor(backgroundColor),
    edgePadding: Dp = TabRowDefaults.ScrollableTabRowPadding,
    indicator: @Composable @UiComposable (tabPositions: List<TabPosition>) -> Unit = @Composable { tabPositions ->
            TabRowDefaults.Indicator(
                Modifier.tabIndicatorOffset(tabPositions[selectedTabIndex])
            )
        },
    divider: @Composable @UiComposable () -> Unit = @Composable {
            TabRowDefaults.Divider()
        },
    tabs: @Composable @UiComposable () -> Unit
): Unit

So if we convert our example from above, we will get this:

@Composable
fun TabScreen() {
    var tabIndex by remember { mutableStateOf(0) }

    val tabs = listOf("Home", "About", "Settings", "More", "Something", "Everything")

    Column(modifier = Modifier.fillMaxWidth()) {
        ScrollableTabRow(selectedTabIndex = tabIndex) {
            tabs.forEachIndexed { index, title ->
                Tab(text = { Text(title) },
                    selected = tabIndex == index,
                    onClick = { tabIndex = index },
                    icon = {
                        when (index) {
                            0 -> Icon(imageVector = Icons.Default.Home, contentDescription = null)
                            1 -> Icon(imageVector = Icons.Default.Info, contentDescription = null)
                            2 -> Icon(imageVector = Icons.Default.Settings, contentDescription = null)
                            3 -> Icon(imageVector = Icons.Default.Lock, contentDescription = null)
                            4 -> Icon(imageVector = Icons.Default.HeartBroken, contentDescription = null)
                            5 -> Icon(imageVector = Icons.Default.Star, contentDescription = null)
                        }
                    }
                )
            }
        }
        when (tabIndex) {
            0 -> HomeScreen()
            1 -> AboutScreen()
            2 -> SettingsScreen()
            3 -> MoreScreen()
            4 -> SomethingScreen()
            5 -> EverythingScreen()
        }
    }
}

How to Create Tabs with Swiping Enabled

Scrollable tabs are nice, but swiping between tabs is even better. Most users will feel that it's more intuitive to swipe between the tabs rather than clicking on each one. If you look at the documentation, you will notice that there are a few options to go with:

1. The swipeable modifier
2. The detectDragGestures modifier
3. The draggable modifier

Not all of these will help us in achieving our goal, each one for its own reasons. If you don’t want to go through the “hassle” of doing things yourself, there is a library from Accompanist called pager that you can use. It allows you to add the ability to either horizontally or vertically create a row/column that reacts to swipes.

Steps to implement it have been covered already and you can use the resources below to learn how to do it:

• https://johncodeos.com/how-to-create-tabs-with-jetpack-compose/
• https://www.rockandnull.com/jetpack-compose-swipe-pager/

If you are like me and you like to do things for yourself and are up for getting your hands dirty, read on.

Option 1: the Swipeable Modifier

The first thing to know about the swipeable modifier is that it is annotated with the @ExperimentalMaterialApi. This means that this API can change between versions of Jetpack Compose and that it isn’t stable.

Apart from that, we need to go over the mechanism that the swipeable modifier uses. It has 3 building blocks:

1. A swipeable state – Denoting the current state and holding data about any on going swipe or swipe related animation.
2. Anchors – A map of values (Float based) restricting the swipe action from the minimum value to the maximum value. It maps anchor points to swipeable states.
3. Thresholds – A value denoting the difference between two known anchors.

@ExperimentalMaterialApi
fun <T : Any?> Modifier.swipeable(
    state: SwipeableState<T>,
    anchors: Map<Float, T>,
    orientation: Orientation,
    enabled: Boolean = true,
    reverseDirection: Boolean = false,
    interactionSource: MutableInteractionSource? = null,
    thresholds: (from, to) -> ThresholdConfig = { _, _ -> FixedThreshold(56.dp) },
    resistance: ResistanceConfig? = resistanceConfig(anchors.keys),
    velocityThreshold: Dp = VelocityThreshold
): Modifier

Regardless of this API being experimental, it just isn’t meant to be used for the swiping gesture we are seeking.

You can. use this modifier for a switch button that the user can drag between on/off positions (as an example). But what would be our anchors in our example? How do we define the thresholds? The swipe a user performs cannot be constrained between two points. Therefore, we’ll let this one go and move on to detectDragGestures.

Option 2: the detectDragGestures Modifier

As the name implies, this modifier detects the drag gesture, which can be quite similar to swiping.

suspend fun PointerInputScope.detectDragGestures(
    onDragStart: (Offset) -> Unit = { },
    onDragEnd: () -> Unit = { },
    onDragCancel: () -> Unit = { },
    onDrag: (change: PointerInputChange, dragAmount: Offset) -> Unit
): Unit

As you can see, the onDrag callback has two arguments:

1. change – of PointerInputChange type, denoting the change in pointer when dragging
2. dragAmount – of Offset type, denoting the amount dragged in x,y values

This callback is called when:

“… waits for pointer down and touch stop in any direction and then calls onDrag for each drag event.”

The upside to use this modifier instead of the draggable one is that it provides you with information about the change in both x and y coordinates.

The downside of it is that it isn’t going to offer a smooth and elegant solution for swiping. This is because of the amount of times the onDrag callback is triggered.

When a user performs a swipe gesture, the onDrag callback is triggered multiple times. This makes it harder to discern when the “drag” gesture has ended completely.

When experimenting with this, I saw the onDrag callback being triggered three times for each swipe gesture. This won’t be a good fit for our use case so let’s check out the draggable modifier.

Option 3: the Draggable Modifier

Think of this modifier as the stripped down version of the one before. This one measures changes in the UI when the user performs a drag gesture in only one orientation (vertical/horizontal). Since we only care about horizontal swipes, this can be a good option.

fun Modifier.draggable(
    state: DraggableState,
    orientation: Orientation,
    enabled: Boolean = true,
    interactionSource: MutableInteractionSource? = null,
    startDragImmediately: Boolean = false,
    onDragStarted: suspend CoroutineScope.(startedPosition: Offset) -> Unit = {},
    onDragStopped: suspend CoroutineScope.(velocity: Float) -> Unit = {},
    reverseDirection: Boolean = false
): Modifier

Here as well there is no similarity to the two other modifiers and we will point out the things to pay attention to:

• state – Similar to the state in the swipeable modifier, only here we are talking about a drag motion.
• onDragStarted – A callback triggered when the drag motion has begun.
• onDragStopped – A callback triggered when the drag motion has ended.

Unlike detectDragGestures, here onDragStopped is called once for every swipe gesture, making this modifier the best candidate for the job.

It’s implementation as a swipe gesture detector in our example is quite robust, so let’s start with some prerequisites:

1. We will be saving the index of the tab currently being viewed in a view model class
2. This index will be of MutableLiveData so that our composables will be able to recompose when the value is changed
3. Each of our screens will add the draggable modifier to its layout
4. We will need to add the runtime-livedata library as we are going to use the observeAsState method.

We will start with #4.

Go to your application’s build.gradle file and add the following dependency:

implementation "androidx.compose.runtime:runtime-livedata:$compose_version"

where $compose_version is the version of Jetpack Compose you are using.

We have also minimized our previous example to hold three screens instead of six, as the solution works for either case and there is no need to create extra boiler plate.

Below is the view model:

class MainViewModel(application: Application) : AndroidViewModel(application) {

    private val _tabIndex: MutableLiveData<Int> = MutableLiveData(0)
    val tabIndex: LiveData<Int> = _tabIndex
    val tabs = listOf("Home", "About", "Settings")

    fun updateTabIndexBasedOnSwipe(isSwipeToTheLeft: Boolean) {
        _tabIndex.value = when (isSwipeToTheLeft) {
            true -> Math.floorMod(_tabIndex.value!!.plus(1), tabs.size)
            false -> Math.floorMod(_tabIndex.value!!.minus(1), tabs.size)
        }
    }

    fun updateTabIndex(i: Int) {
        _tabIndex.value = i
    }

}

• tabIndex is in charge of holding the currently selected index.
• index is the exposed tabIndex.
• tabs is the list of tab names.
• The method updateTabIndexBasedOnSwipe is triggered when a swipe happens and performs the calculation of where to move the tabIndex to.

Each screen is made up of the same layout:

@Composable
fun AboutScreen(viewModel: MainViewModel) {

    var isSwipeToTheLeft by remember { mutableStateOf(false) }
    val dragState = rememberDraggableState(onDelta = { delta ->
        isSwipeToTheLeft = delta > 0
    })

    Column(modifier = Modifier.fillMaxSize().draggable(
        state = dragState,
        orientation = Orientation.Horizontal,
        onDragStarted = {  },
        onDragStopped = {
            viewModel.updateTabIndexBasedOnSwipe(isSwipeToTheLeft = isSwipeToTheLeft)
        }),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center) {
        Row(modifier = Modifier.align(Alignment.CenterHorizontally)) {
            Text(
                text = "About",
                textAlign = TextAlign.Center,
                fontSize = 20.sp,
                fontWeight = FontWeight.Bold
            )
        }
    }
}

• isSwipeToTheLeft is a Boolean indicating the direction of the swipe.
• dragState holds the state of the drag being performed and updates isSwipeToTheLeft according to the delta.
• When the callback onDragStopped is called, we are calling the exposed viewModel method updateTabIndexBasedOnSwipe.

And finally, our TabLayout:

@Composable
fun TabLayout(viewModel: MainViewModel) {
    val tabIndex = viewModel.tabIndex.observeAsState()
    Column(modifier = Modifier.fillMaxWidth()) {
        TabRow(selectedTabIndex = tabIndex.value!!) {
            viewModel.tabs.forEachIndexed { index, title ->
                Tab(text = { Text(title) },
                    selected = tabIndex.value!! == index,
                    onClick = { viewModel.updateTabIndex(index) },
                    icon = {
                        when (index) {
                            0 -> Icon(imageVector = Icons.Default.Home, contentDescription = null)
                            1 -> Icon(imageVector = Icons.Default.Info, contentDescription = null)
                            2 -> Icon(imageVector = Icons.Default.Settings, contentDescription = null)
                        }
                    }
                )
            }
        }

        when (tabIndex.value) {
            0 -> HomeScreen(viewModel = viewModel)
            1 -> AboutScreen(viewModel = viewModel)
            2 -> SettingsScreen(viewModel = viewModel)
        }
    }
}

• Notice that when a tab is selected, we are updating the currently selected tab in the viewModel with updateTabIndex.

Putting it all together yields:

A few words regarding what we have accomplished. You might have noticed that there is some boilerplate we are adding for each of our screens that results in repetition. Each screen is saving the state of the drag.

To improve on that, we can move the draggableState to the view model, like so:

class MainViewModel(application: Application) : AndroidViewModel(application) {

    private val _tabIndex: MutableLiveData<Int> = MutableLiveData(0)
    val tabIndex: LiveData<Int> = _tabIndex
    val tabs = listOf("Home", "About", "Settings")

    var isSwipeToTheLeft: Boolean = false
    private val draggableState = DraggableState { delta ->
        isSwipeToTheLeft= delta > 0
    }

    private val _dragState = MutableLiveData<DraggableState>(draggableState)
    val dragState: LiveData<DraggableState> = _dragState

    fun updateTabIndexBasedOnSwipe() {
        _tabIndex.value = when (isSwipeToTheLeft) {
            true -> Math.floorMod(_tabIndex.value!!.plus(1), tabs.size)
            false -> Math.floorMod(_tabIndex.value!!.minus(1), tabs.size)
        }
    }

    fun updateTabIndex(i: Int) {
        _tabIndex.value = i
    }

}

And that reduces the boilerplate a bit, since each screen now looks like:

@Composable
fun AboutScreen(viewModel: MainViewModel) {

    Column(modifier = Modifier.fillMaxSize().draggable(
        state = viewModel.dragState.value!!,
        orientation = Orientation.Horizontal,
        onDragStarted = {  },
        onDragStopped = {
            viewModel.updateTabIndexBasedOnSwipe()
        }),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center) {
        Row(modifier = Modifier.align(Alignment.CenterHorizontally)) {
            Text(
                text = "About",
                textAlign = TextAlign.Center,
                fontSize = 20.sp,
                fontWeight = FontWeight.Bold
            )
        }
    }
}

I hope this article gave you the necessary tools to create your own tabs UI in Jetpack Compose.

The example shown above can be found here.

And if you would like to read other articles I have written, you can check them out here.

References:

• Material Design page about Tabs
• Gestures In Jetpack Compose

If you have ever worked with a database or fetching data from a server, this should all be familiar to you. If not, you have come to the right place.

In this tutorial, we will go over:

• How to setup serialization in a Jetpack Compose project
• How to serialize a data class
• How to de-serialize a data class

You might be asking yourself, what’s so special about serialization in Jetpack Compose? In essence, there isn’t a lot of difference than with a regular Kotlin Android project. The only difference is in the setup.

How to Set Everything Up

Each version of Jetpack Compose corresponds with a version of Kotiln that it is compatible with. Each version of the kotlin-serialization library is also compatible with a specific version of Kotlin. So you need to make sure that each of the three parts in this tripod are compatible with one another.

How can you that?

Your first resource you'll want to consult is the Compose to Kotlin Compatibility Map.

Here you can see which version of Jetpack Compose corresponds to which Kotlin version.

The second resource you will need is the releases page for the kotlin-serialization library. There you will find which library version is compatible with which Kotlin version.

Confused? 😕

Let’s illustrate this with an example:

• Your Jetpack Compose version is 1.1.0.
• Looking over the compatibility map, you see it is compatible with Kotlin version 1.6.10.
• Heading to the releases page of kotlin-serialization library, you see that the version of the kotlin-serialization library that you need to use is 1.3.2.

Head into your project level build.gradle file, and inside the buildscript object, in the dependencies section, put in classpath for the kotlin-serialization library with the version you need.

dependencies {
        ...
        classpath "org.jetbrains.kotlin:kotlin-serialization:X.Y.Z"
 }

Then, head over to your application build.gradle file and do these two things:

1. Add the id ‘org.jetbrains.kotlin.plugin.serialization’ inside of the plugins at the top of the file:

plugins {
   ...
   id 'org.jetbrains.kotlin.plugin.serialization'
}

2. At the bottom of the file, inside the dependencies section add implementation ‘org.jetbrains.kotlinx:kotlinx-serialization-json:X.Y.Z’:

dependencies {
   ...
   implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:X.Y.Z'
}

Sync your project and you should be good to go.

Note that we are using the json format of the library, but there are other formats that are supported as well:

• Protocol Buffers
• CBOR (Concise Binary Object Representation)
• Properties
• HOCON (Human Optimized Config Object Notation)

⚠️ If you encounter any errors, make sure the versions you put are correct

How to Build Your Data Class

In order to have something we can serialize and later de-serialize, we need to work with data classes.

Creating a data class is simple. If you are using Android Studio, just right click inside your project’s module and choose New Kotlin file. Enter your class name and then append the data keyword before it.

For the sake of this article, let's say we are working with an API that returns a list of users. Each user object has a range of attributes it can have (just to name a few):

• First name
• Last name
• Age
• Birthdate
• Id

To make our data class serializable, all you need to do is add the @Serializable annotation above the class declaration.

@Serializable
data class UserModel(
   val firstName: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long
)

Pretty nifty, right?

Well, there’s more.

The variable that will hold the user’s first name is written as firstName. That means that in the response from our server, it needs to return in a field with the same name.

Sometimes, in API responses, the keys are not written in camelCase, but rather in kebab_case. That would mean that the key for first name, might be first_name. In that case, we would have to write it out like this:

@Serializable
data class UserModel(
   val first_name: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long
)

But that is not the convention for property names in Kotlin.

So what can we do?

We can use the @SerialName annotation. This allows us to mark what the name of the field will be from the response and then write anything as the property for it.

@Serializable
data class UserModel(
   @SerialName("first_name")
   val firstName: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long
)

How to Serialize and De-Serialize

Now that our data class is set up, let’s enjoy the fruits of our labor. Whenever we need to serialize our data class, we will use the Json.encodeToString method:

val dataAsString: String = Json.encodeToString(user)

When we run the above line of code, we will get our data class in string form.

De-serializing our data is as simple as serializing it. We will use the Json.decodeFromString method:

val user: UserModel = Json.decodeFromString<UserModel>(dataAsString)

✋ Notice that we specified which type of data we want to de-serialize to with the type parameter ().

_Photo by [Unsplash](https://unsplash.com/@macroman?utm_source=ghost&utm_medium=referral&utm_campaign=api-credit">Immo Wegmann / <a href="https://unsplash.com/?utm_source=ghost&utm_medium=referral&utmcampaign=api-credit)

Time for some extra credit.

Let’s say that in your data class you have a field that you don’t want to serialize. If we take our UserModel class, imagine that we want to have a user’s actual picture (bitmap).

@Serializable
data class UserModel(
   @SerialName("first-name")
   val firstName: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long,
   var photo: Bitmap?
)

This is not something we will get from our API call, so how can we exclude it? Because if we don’t, our serialization will fail.

Here to our rescue is the @Transient annotation.

@Serializable
data class UserModel(
   @SerialName("first-name")
   val firstName: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long,
   @Transient
   var photo: Bitmap?
)

This will exclude the marked field from being serialized and de-serialized.

• If you want to see a real life example of using serialization inside a project, you can check out a project I made here
• And if you would like to read other articles I have written, you can go here
• For more information about the kotlin-serialization library, you can go here

Thank you for reading! Happy serializing.

In the old system, we used OnClickListeners and other interfaces. In Compose, we can take full advantage of Kotlin’s Sealed Classes, Function Types and Lambda Expressions.

If you do not know what a composable is, consider reading this article which explains the fundamentals.

How to Model UI Events with a Sealed Class

First, we must learn what is meant by UI Events and how to model them with Sealed Classes.

I have described this same process for Java and Kotlin (with the old view system) before, so I will keep this brief.

The Process

For each screen or sub-screen of your UI, ask yourself this question: What are all the different ways which the user can interact with it?

Let's take an example from my first app built fully in compose, Graph Sudoku:

Screenshot of a Sudoku Android App

The sealed class I use to represent the UI interactions of this screen looks like this:

sealed class ActiveGameEvent {
    data class OnInput(val input: Int) : ActiveGameEvent()
    data class OnTileFocused(val x: Int, 
    val y: Int) : ActiveGameEvent()
    object OnNewGameClicked : ActiveGameEvent()
    object OnStart : ActiveGameEvent()
    object OnStop : ActiveGameEvent()
}

To explain briefly:

• OnInput represents a user touching an input button (like 0, 1, 2, 3, 4)

• OnTileFocused represents a user selecting a tile (like the amber highlighted one)

• OnNewGameClicked is self-explanatory

• OnStart and OnStop are lifecycle events which my composables do not care about, but they are used in the Activity which acts as a Container for the composables

Once you have your sealed class set up, you can now handle a wide variety of events using a single event handler function. Sometimes it might make more sense to have multiple event handler functions, so keep in mind that this approach must be adapted to your project's specific requirements.

How to Connect Your Software Architecture

What you have handling these events is totally up to you. Some people think that MVVM is the golden standard of software architectures, but it seems like more and more people are realizing that there is no single architecture which works best for every situation.

For Android with Compose, my current approach is to use a very 3rd party minimalist approach which typically has these things in each feature (screen):

• A (Presentation) Logic class as an event handler

• A ViewModel to store the data necessary to render the View (as the name implies)

• An Activity which acts as a Container (not a god object)

• Composables to form the View

Model-View-Whatever

I do not care what you use as long as you are applying separation of concerns. This is how I arrived at this architecture, by simply asking what should and should not be put together in the same class.

Whether you want your ViewModel, a Fragment, or an Activity to be your event handler, all of them can be set up the same way: Function Types!

Within your class of choice, set up an event handler function which accepts your sealed class as its argument:

class ActiveGameLogic(
    private val container: ActiveGameContainer?,
    private val viewModel: ActiveGameViewModel,
    private val gameRepo: IGameRepository,
    private val statsRepo: IStatisticsRepository,
    dispatcher: DispatcherProvider
) : BaseLogic<ActiveGameEvent>(dispatcher),
    CoroutineScope {
    //...
    override fun onEvent(event: ActiveGameEvent) {
        when (event) {
            is ActiveGameEvent.OnInput -> onInput(
                event.input,
                viewModel.timerState
            )
            ActiveGameEvent.OnNewGameClicked -> onNewGameClicked()
            ActiveGameEvent.OnStart -> onStart()
            ActiveGameEvent.OnStop -> onStop()
            is ActiveGameEvent.OnTileFocused -> onTileFocused(event.x, event.y)
        }
    }
    //...
}

This approach is very organized and makes it easy to test every Unit in this 3rd party library free class through a single entry point.

However, we are not done yet. Naturally, we need a way to get a reference to this event handler function, onEvent, to our Composables. We can do this using a function reference:

class ActiveGameActivity : AppCompatActivity(), ActiveGameContainer {
    private lateinit var logic: ActiveGameLogic

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val viewModel = ActiveGameViewModel()

        setContent {
            ActiveGameScreen(
                onEventHandler = logic::onEvent,
                viewModel
            )
        }

        logic = buildActiveGameLogic(this, viewModel, applicationContext)
    }

      //...
}

I am sure some of you are wondering why I am using an Activity. You can ask me during a livestream Q&A sometime for a detailed answer.

In short, Fragments appear to be a bit pointless with Compose with my approach to architecture (I do not use Jetpack Navigation), and there is nothing wrong with using Activities as a feature specific container. Just avoid writing god activities, basically.

To be specific, the way you make a reference to a function in Kotlin, is by providing the class/interface name (or skip that if it is a Top-Level function), followed by two colons, and the name of the function without any arguments or brackets:

onEventHandler = logic::onEvent

How to Replace onClickListener With Jetpack Compose onClick Modifier

With that stuff ready, we can look at how this works within the composable. Naturally, your root composable will need the event handler function as a parameter:

@Composable
fun ActiveGameScreen(
    onEventHandler: (ActiveGameEvent) -> Unit,
    viewModel: ActiveGameViewModel
) {
//...
}

It can be a bit tricky to get function type syntax correctly, but understand that this really is a reference to a function, which is not so different from a reference to a class.

Just as you should not build god objects, you should not build giant composables:

1. Break your UI down into the smallest reasonable parts

2. Wrap them in a composable function

3. For each composable which has a UI interaction associated with it, it must be given a reference to your event handler function

Here is a composable which represents the input buttons of the Sudoku app, which is given the event handler by reference:

@Composable
fun SudokuInputButton(
    onEventHandler: (ActiveGameEvent) -> Unit,
    number: Int
) {
    Button(
        onClick = { onEventHandler.invoke(ActiveGameEvent.OnInput(number)) },
        modifier = Modifier
            .requiredSize(56.dp)
            .padding(2.dp)
    ) {
        Text(
            text = number.toString(),
            style = inputButton.copy(color = MaterialTheme.colors.onPrimary),
            modifier = Modifier.fillMaxSize()
        )
    }
}

To actually pass the event to the logic class, we must use the invoke function, which will accept arguments as per the function type definition (which accepts an ActiveGameEvent in this case).

At this point, you are ready to handle UI interaction events in Kotlin (compose or not) by taking full advantage of this beautiful and modern programming language.

If you liked this article, share it on social media and consider checking out the resources below to support an independent programmer and content creator.

Social

You can find me on Instagram here and on Twitter here.

Here are some of my tutorials & courses

https://youtube.com/wiseass https://www.freecodecamp.org/news/author/ryan-michael-kay/ https://skl.sh/35IdKsj (introduction to Android with Android Studio)