Jetpack Compose on MangoDriod

Building a Reusable Speech-to-Text Component in Jetpack Compose

Thu, 12 Feb 2026 21:30:00 +0530

TL;DR - Why You Should Add Voice Input

Voice input can dramatically improve UX, yet most apps don’t use it. Here’s why you should:

✅ Zero app size increase - Uses Android’s native speech recognition (no libraries!) ✅ No permissions required - Works out of the box ✅ 3-5x faster input - Users can speak 150+ words/min vs typing 40 words/min ✅ Better accessibility - Essential for users with motor impairments ✅ Reduces friction - One tap vs multiple keyboard interactions ✅ Professional polish - Shows attention to UX details

The catch? It requires network connectivity and device support. But with proper availability checks, you can gracefully hide the feature when unavailable—making it a pure win when present.

Why Most Apps Skip This Feature

Despite being a native Android capability since API 8, many developers overlook voice input because:

Assumed complexity - Developers think it requires heavy ML libraries
Unclear implementation - Documentation is scattered
Network dependency concerns - Fear of handling edge cases
Device fragmentation worries - Uncertainty about availability
“The keyboard already has it” - The most common misconception

The truth? It’s simpler than adding a date picker, and this guide shows you how to handle all edge cases properly.

“But Users Have Voice Input on Their Keyboard Already!”

This is the most common objection developers raise. Yes, most mobile keyboards (Gboard, SwiftKey, Samsung Keyboard) have a mic button. But here’s why in-app voice input is still essential:

The Reality of Keyboard Voice Input Usage

📊 Usage statistics show a problem:

Most users don’t even know the keyboard mic button exists
Many forget about it after the initial setup
Some disable it accidentally during keyboard customization
The keyboard mic is visually small and easy to miss
Users must actively look for it among other keyboard buttons

Why In-App Voice Input is Superior

1. Discoverability

❌ Keyboard mic: Hidden among 30+ keyboard keys, looks like any other button
✅ In-app mic: Prominent, contextual, right next to the input field

Example: A text field with a mic icon in the trailing position is immediately obvious. The keyboard mic? Users have to open the keyboard, scan for it, and remember it exists.

2. Context-Aware UX

// In-app voice can be contextual
TextField(
    label = { Text("Product Review") },
    trailingIcon = { MicIcon() }  // Clear purpose: "Speak your review"
)

The keyboard mic has no context - it’s the same button whether you’re entering an email, a password, or a product review. In-app voice input can show field-specific prompts like “Describe your issue” or “Speak your address”.

3. User Intent and Flow

Keyboard mic: Requires users to:
1. Tap the input field
2. Wait for keyboard to appear
3. Look for the mic button among keyboard keys
4. Tap the mic
5. Speak
In-app mic: Simplified flow:
1. Tap the mic icon (no keyboard needed!)
2. Speak

Result: 2 fewer steps and no keyboard lag.

4. Visual Prominence

Keyboard Mic	In-App Mic
5-6mm size typical	Can be 24-32dp (12-16mm)
Gray/neutral color	App-themed, stands out
Among 30+ keys	Isolated, clear purpose
Same across all apps	Consistent with your app design

5. Accessibility Considerations

Users with motor impairments or visual limitations benefit significantly:

Larger, easier-to-tap target
Better contrast and visibility
Screen readers can announce it contextually
Doesn’t require precise keyboard navigation

6. User Psychology

Explicit invitation > Hidden capability

When users see a mic icon next to a text field, it:

Signals that voice input is encouraged
Reduces friction - they don’t need to hunt for it
Increases adoption - visible features get used more
Feels intentional - the app wants them to use voice

The keyboard mic feels like a generic fallback. The in-app mic feels like a first-class feature.

Real-World Data Points

While specific metrics vary by app, general patterns show:

📈 5-10x higher voice input usage with prominent in-app mic icons
🎯 New user discovery - many users don’t realize keyboard voice exists
♿ Accessibility gains - significant usage increase among users with disabilities
📱 Mobile-first users especially benefit (small screen, fat fingers)

The Hybrid Approach: Best of Both Worlds

The ideal solution is not either/or, but both:

✅ In-app mic for discoverability and context ✅ Keyboard mic still works as a fallback

Users get:

A prominent, obvious voice input option
Fallback if they prefer keyboard mic
Contextual prompts and better UX
No downsides!

When “Just Use the Keyboard” Fails

Some scenarios where keyboard voice input is insufficient:

Custom keyboards - Not all keyboards have voice input
Enterprise devices - Some organizations disable keyboard voice for security
Locked-down keyboards - Educational or restricted environments
Non-Google keyboards - Third-party keyboards may lack voice features
Disabled by user - Some users disable keyboard permissions

Your in-app implementation works regardless of keyboard choice.

The Bottom Line

“Users have voice on their keyboard” is like saying:

“Don’t add a search icon, users can use Ctrl+F”
“Don’t add a share button, users can copy-paste”
“Don’t add undo, users can manually fix mistakes”

Just because a capability exists somewhere doesn’t mean it’s discoverable or convenient.

In-app voice input is about removing friction and guiding users toward better UX. The fact that keyboard voice exists is great - your in-app implementation makes it more likely to actually be used.

Ever wanted to add voice input to your Android app with minimal effort? Speech-to-Text functionality can dramatically improve user experience, especially for note-taking, messaging, or search features.

In this guide, we’ll build a clean, reusable Speech-to-Text component using Jetpack Compose that wraps Android’s native speech recognition API.

🎯 What We’re Building

A composable speech recognition system with:

✅ Simple API - One composable function to handle everything
✅ Lifecycle-aware - Properly managed with Activity Result API
✅ Locale support - Respects app language settings
✅ Availability checking - Gracefully handles devices without speech recognition
✅ Reusable state - Clean separation of concerns

🏗️ Architecture Overview

Our implementation consists of three main components:

SystemSpeechToTextHelper - A utility object that handles Android’s RecognizerIntent
SpeechToTextState - A state holder that manages the speech recognition launcher
rememberSpeechToText() - A composable function that creates and remembers the state
SpeechToTextButton (Bonus) - A ready-to-use UI component

📝 Implementation

1️⃣ The Helper Object

First, let’s create a helper object to encapsulate all Android-specific speech recognition logic:

object SystemSpeechToTextHelper {
    fun getAppLocale(): Locale {
        return try {
            Locale.forLanguageTag(Language.currentLocale.value.code)
        } catch (e: Exception) {
            Locale.getDefault()
        }
    }

    fun createRecognitionIntent(
        languageModel: String = RecognizerIntent.LANGUAGE_MODEL_FREE_FORM,
        locale: Locale = getAppLocale(),
        prompt: String? = null,
        maxResults: Int = 1
    ): Intent {
        return Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH).apply {
            putExtra(RecognizerIntent.EXTRA_LANGUAGE_MODEL, languageModel)
            putExtra(RecognizerIntent.EXTRA_LANGUAGE, locale.toLanguageTag())
            putExtra(RecognizerIntent.EXTRA_MAX_RESULTS, maxResults)
            prompt?.let { putExtra(RecognizerIntent.EXTRA_PROMPT, it) }
        }
    }

    fun extractSpokenText(result: ActivityResult): String? {
        return if (result.resultCode == Activity.RESULT_OK) {
            result.data
                ?.getStringArrayListExtra(RecognizerIntent.EXTRA_RESULTS)
                ?.firstOrNull()
                ?.takeIf { it.isNotBlank() }
        } else {
            null
        }
    }

    fun isRecognitionAvailable(context: Context): Boolean {
        val pm = context.packageManager
        val activities = pm.queryIntentActivities(
            Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH),
            PackageManager.MATCH_DEFAULT_ONLY
        )
        return activities.isNotEmpty()
    }
}

Key Features:

🌍 Locale handling - Automatically uses your app’s current language
🎤 Flexible configuration - Customize prompt, language model, and result count
✅ Validation - Ensures speech recognition is available on the device
🧹 Clean extraction - Filters out blank results

2️⃣ The State Holder

Next, we create a state class that manages the speech recognition lifecycle:

@Stable
class SpeechToTextState(
    private val launcher: ManagedActivityResultLauncher,
    private val prompt: String?,
    val isAvailable: Boolean
) {
    fun launch(
        customPrompt: String? = prompt,
        customLocale: Locale? = null
    ) {
        val intent = SystemSpeechToTextHelper.createRecognitionIntent(
            prompt = customPrompt,
            locale = customLocale ?: SystemSpeechToTextHelper.getAppLocale()
        )
        launcher.launch(intent)
    }
}

Why @Stable? The @Stable annotation tells Compose that this class follows specific stability contracts, allowing for better recomposition optimizations.

3️⃣ The Composable Function

Now comes the magic - a composable that ties everything together:

@Composable
fun rememberSpeechToText(
    prompt: String? = null,
    onResult: (String) -> Unit
): SpeechToTextState {
    val context = LocalContext.current

    val launcher = rememberLauncherForActivityResult(
        contract = ActivityResultContracts.StartActivityForResult()
    ) { result ->
        SystemSpeechToTextHelper.extractSpokenText(result)?.let { spokenText ->
            onResult(spokenText)
        }
    }

    val isAvailable = remember {
        SystemSpeechToTextHelper.isRecognitionAvailable(context)
    }

    return remember(launcher, prompt, isAvailable) {
        SpeechToTextState(
            launcher = launcher,
            prompt = prompt,
            isAvailable = isAvailable
        )
    }
}

Key Points:

🔄 Activity Result API - Modern way to handle activity results
💾 Remembered state - Survives recompositions
🎯 Callback pattern - Clean result handling via lambda

4️⃣ Bonus: Ready-to-Use Button Component

For convenience, here’s a pre-built button component:

@Composable
fun SpeechToTextButton(
    speechToTextState: SpeechToTextState,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    iconSize: Dp = 24.dp,
    tint: Color = Color.Unspecified,
    contentDescription: String? = null
) {
    IconButton(
        onClick = speechToTextState::launch,
        enabled = enabled && speechToTextState.isAvailable,
        modifier = modifier
    ) {
        Icon(
            painter = painterResource(id = R.drawable.ic_mic),
            contentDescription = contentDescription,
            tint = tint,
            modifier = Modifier.size(iconSize)
        )
    }
}

🚀 Real-World Implementation Examples

Example 1: TextField with Voice Input (Production-Ready)

Here’s how to properly integrate voice input with a text field, including validation and network checking:

@Composable
fun SmartTextField(
    value: String,
    onValueChange: (String) -> Unit,
    modifier: Modifier = Modifier,
    label: String = "",
    placeholder: String = "",
    isError: Boolean = false,
    errorMessage: String? = null,
    maxLength: Int? = null,
    singleLine: Boolean = true
) {
    val context = LocalContext.current
    var showNetworkWarning by remember { mutableStateOf(false) }

    // Check network connectivity
    val isNetworkAvailable = remember {
        val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
        cm.activeNetwork != null
    }

    val speechToText = rememberSpeechToText(
        prompt = "Speak $label"
    ) { spokenText ->
        // Handle max length validation
        val newText = if (maxLength != null) {
            spokenText.take(maxLength)
        } else {
            spokenText
        }
        onValueChange(newText)
    }

    Column(modifier = modifier) {
        OutlinedTextField(
            value = value,
            onValueChange = { newValue ->
                // Enforce max length on manual input too
                val sanitized = if (maxLength != null) {
                    newValue.take(maxLength)
                } else {
                    newValue
                }
                onValueChange(sanitized)
            },
            label = { Text(label) },
            placeholder = { Text(placeholder) },
            isError = isError,
            singleLine = singleLine,
            modifier = Modifier.fillMaxWidth(),
            trailingIcon = {
                // Only show mic icon if speech recognition is available
                if (speechToText.isAvailable) {
                    IconButton(
                        onClick = {
                            if (isNetworkAvailable) {
                                speechToText.launch()
                            } else {
                                showNetworkWarning = true
                            }
                        }
                    ) {
                        Icon(
                            painter = painterResource(id = R.drawable.ic_mic),
                            contentDescription = "Voice input for $label",
                            tint = if (isNetworkAvailable) {
                                MaterialTheme.colorScheme.primary
                            } else {
                                MaterialTheme.colorScheme.onSurface.copy(alpha = 0.38f)
                            }
                        )
                    }
                }
            },
            supportingText = {
                when {
                    errorMessage != null && isError -> {
                        Text(
                            text = errorMessage,
                            color = MaterialTheme.colorScheme.error
                        )
                    }
                    maxLength != null -> {
                        Text(
                            text = "${value.length}/$maxLength",
                            modifier = Modifier.fillMaxWidth(),
                            textAlign = TextAlign.End
                        )
                    }
                }
            }
        )

        // Network warning
        if (showNetworkWarning) {
            Text(
                text = "Voice input requires internet connection",
                color = MaterialTheme.colorScheme.error,
                style = MaterialTheme.typography.bodySmall,
                modifier = Modifier.padding(start = 16.dp, top = 4.dp)
            )
            LaunchedEffect(Unit) {
                delay(3000)
                showNetworkWarning = false
            }
        }
    }
}

Usage:

@Composable
fun FeedbackForm() {
    var userName by remember { mutableStateOf("") }
    var feedback by remember { mutableStateOf("") }
    val maxFeedbackLength = 500

    Column(modifier = Modifier.padding(16.dp)) {
        SmartTextField(
            value = userName,
            onValueChange = { userName = it },
            label = "Your Name",
            placeholder = "John Doe",
            maxLength = 50,
            singleLine = true
        )

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

        SmartTextField(
            value = feedback,
            onValueChange = { feedback = it },
            label = "Feedback",
            placeholder = "Tell us what you think...",
            maxLength = maxFeedbackLength,
            singleLine = false
        )
    }
}

Example 2: Search Bar with Voice Input

@Composable
fun VoiceEnabledSearchBar(
    query: String,
    onQueryChange: (String) -> Unit,
    onSearch: () -> Unit,
    modifier: Modifier = Modifier
) {
    val speechToText = rememberSpeechToText(
        prompt = "What are you looking for?"
    ) { spokenText ->
        onQueryChange(spokenText)
        // Auto-search after voice input
        onSearch()
    }

    SearchBar(
        query = query,
        onQueryChange = onQueryChange,
        onSearch = { onSearch() },
        active = false,
        onActiveChange = {},
        modifier = modifier,
        leadingIcon = {
            Icon(
                imageVector = Icons.Default.Search,
                contentDescription = "Search"
            )
        },
        trailingIcon = {
            Row {
                // Clear button
                if (query.isNotEmpty()) {
                    IconButton(onClick = { onQueryChange("") }) {
                        Icon(
                            imageVector = Icons.Default.Close,
                            contentDescription = "Clear"
                        )
                    }
                }

                // Voice input button (only if available)
                if (speechToText.isAvailable) {
                    IconButton(onClick = { speechToText.launch() }) {
                        Icon(
                            painter = painterResource(id = R.drawable.ic_mic),
                            contentDescription = "Voice search"
                        )
                    }
                }
            }
        },
        placeholder = { Text("Search products...") }
    ) {
        // Search suggestions
    }
}

Example 3: Multi-line Text Input with Append Mode

Perfect for note-taking or messaging apps:

@Composable
fun VoiceNoteEditor() {
    var noteContent by remember { mutableStateOf("") }
    var isRecording by remember { mutableStateOf(false) }

    val speechToText = rememberSpeechToText(
        prompt = "Speak your note"
    ) { spokenText ->
        // Intelligently append or replace
        noteContent = when {
            noteContent.isEmpty() -> spokenText
            noteContent.endsWith(".") || noteContent.endsWith("!") || noteContent.endsWith("?") ->
                "$noteContent $spokenText"
            else ->
                "$noteContent. $spokenText"
        }
        isRecording = false
    }

    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(16.dp)
    ) {
        OutlinedTextField(
            value = noteContent,
            onValueChange = { noteContent = it },
            modifier = Modifier
                .fillMaxWidth()
                .weight(1f),
            placeholder = {
                Text("Start typing or tap the mic to speak...")
            },
            textStyle = MaterialTheme.typography.bodyLarge
        )

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

        Row(
            modifier = Modifier.fillMaxWidth(),
            horizontalArrangement = Arrangement.SpaceBetween,
            verticalAlignment = Alignment.CenterVertically
        ) {
            // Word count
            Text(
                text = "${noteContent.split("\\s+".toRegex()).size} words",
                style = MaterialTheme.typography.bodySmall,
                color = MaterialTheme.colorScheme.onSurfaceVariant
            )

            // Voice input button
            if (speechToText.isAvailable) {
                FilledTonalButton(
                    onClick = {
                        isRecording = true
                        speechToText.launch()
                    }
                ) {
                    Icon(
                        painter = painterResource(id = R.drawable.ic_mic),
                        contentDescription = null,
                        modifier = Modifier.size(20.dp)
                    )
                    Spacer(modifier = Modifier.width(8.dp))
                    Text(if (isRecording) "Listening..." else "Add Voice Note")
                }
            }
        }
    }
}

Example 4: Form with Conditional Voice Input

Shows how to conditionally enable voice input based on field type:

@Composable
fun UserRegistrationForm() {
    var name by remember { mutableStateOf("") }
    var email by remember { mutableStateOf("") }
    var bio by remember { mutableStateOf("") }

    Column(modifier = Modifier.padding(16.dp)) {
        // Name field - voice input enabled
        SmartTextField(
            value = name,
            onValueChange = { name = it },
            label = "Full Name",
            maxLength = 50
        )

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

        // Email field - voice input disabled (too error-prone)
        OutlinedTextField(
            value = email,
            onValueChange = { email = it },
            label = { Text("Email") },
            keyboardOptions = KeyboardOptions(
                keyboardType = KeyboardType.Email
            ),
            modifier = Modifier.fillMaxWidth()
            // No voice input for email - typing is more accurate
        )

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

        // Bio field - voice input enabled
        SmartTextField(
            value = bio,
            onValueChange = { bio = it },
            label = "Bio",
            placeholder = "Tell us about yourself...",
            maxLength = 200,
            singleLine = false
        )
    }
}

⚠️ Critical Implementation Guidelines

1. Always Check Availability

Never show the mic icon if speech recognition is unavailable. This creates a poor UX when users tap it and nothing happens.

// ✅ GOOD - Only show when available
if (speechToText.isAvailable) {
    SpeechToTextButton(speechToTextState = speechToText)
}

// ❌ BAD - Shows disabled button (confusing UX)
SpeechToTextButton(
    speechToTextState = speechToText,
    enabled = speechToText.isAvailable  // Don't do this!
)

Why? On devices without Google services (some custom ROMs, enterprise devices), the feature won’t work. Hiding it entirely is cleaner than showing a permanently disabled button.

2. Handle Network Connectivity

Speech recognition requires active internet connection. Check before launching:

fun isNetworkAvailable(context: Context): Boolean {
    val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
    return cm.activeNetwork != null
}

// Usage
val isNetworkAvailable = remember {
    isNetworkAvailable(context)
}

IconButton(
    onClick = {
        if (isNetworkAvailable) {
            speechToText.launch()
        } else {
            // Show snackbar or toast
            Toast.makeText(context, "Voice input requires internet", Toast.LENGTH_SHORT).show()
        }
    }
) {
    Icon(
        painter = painterResource(id = R.drawable.ic_mic),
        tint = if (isNetworkAvailable) {
            MaterialTheme.colorScheme.primary
        } else {
            MaterialTheme.colorScheme.onSurface.copy(alpha = 0.38f)
        }
    )
}

Best Practice: Show the mic icon in a dimmed state when offline, and display a brief message when tapped.

3. Input Validation After Voice Input

Always validate voice input just like you would keyboard input:

val speechToText = rememberSpeechToText { spokenText ->
    // Sanitize and validate
    val sanitized = spokenText
        .trim()
        .take(maxLength)
        .filter { it.isLetterOrDigit() || it.isWhitespace() }

    // Check if valid
    if (sanitized.isNotEmpty()) {
        inputValue = sanitized
    } else {
        showError("Invalid input received")
    }
}

Common validations:

Length limits - Trim to max length
Character filtering - Remove special chars if needed
Empty checks - Handle blank results
Format validation - Email, phone, etc.

4. Permissions - None Required!

Good news: No runtime permissions needed! Android’s speech recognition uses Google’s cloud service, which handles all the heavy lifting.

This is a huge advantage over custom speech recognition libraries that require RECORD_AUDIO permission.

5. Locale and Language Support

By default, the implementation respects your app’s current locale:

fun getAppLocale(): Locale {
    return try {
        Locale.forLanguageTag(Language.currentLocale.value.code)
    } catch (e: Exception) {
        Locale.getDefault()
    }
}

For multilingual apps, you can override the locale per-field:

// Spanish input for a specific field
speechToText.launch(customLocale = Locale("es", "ES"))

// French input
speechToText.launch(customLocale = Locale.FRANCE)

6. When NOT to Use Voice Input

Some fields are better suited for keyboard input:

❌ Email addresses - Punctuation and special characters are error-prone ❌ Passwords - Security risk + poor accuracy ❌ Credit card numbers - High error rate + security concerns ❌ URLs - Complex syntax not recognized well ❌ Code snippets - Special characters and formatting issues

✅ Good use cases: ✔ Names, addresses, descriptions ✔ Search queries ✔ Notes and messages ✔ Feedback and reviews ✔ Long-form text content

📊 UX Impact: The Numbers

Why voice input matters for your app’s user experience:

Metric	Typing	Voice Input	Improvement
Average Speed	40 words/min	150+ words/min	3.75x faster
Error Rate	2-3%	5-8% (but faster to correct)	Context dependent
User Effort	High (small keyboards)	Low (hands-free)	Significantly lower
Accessibility	Difficult for some users	Easy for most users	Universal access

Real-world impact:

📝 A 100-word product review takes 2.5 minutes typing vs 40 seconds speaking
🔍 Voice search feels instantaneous vs typing lag
♿ Critical for users with motor impairments, RSI, or visual limitations
🌍 Easier for non-native keyboard users

✅ Why This Implementation is Superior

Compared to Keyboard Input:

✔ 3-5x faster input for long text ✔ Lower cognitive load - speaking is more natural than typing ✔ Better mobile experience - no tiny keyboard frustration ✔ Hands-free operation - can be used while multitasking

Compared to Third-Party Libraries:

✔ Zero app size increase - uses system APIs ✔ No permissions required - no RECORD_AUDIO prompt ✔ Always up-to-date - Google maintains the recognition engine ✔ No API keys or quotas - completely free ✔ Better privacy - uses Google’s standard speech service (same as Gboard)

Compared to Custom ML Models:

✔ No model training needed ✔ No storage for ML models (models can be 50MB+) ✔ Supports 100+ languages out of the box ✔ Continuously improving - benefits from Google’s updates

🎯 When Voice Input Makes Sense

Perfect Use Cases:

📝 Note-taking and memos - Natural dictation flow
💬 Messaging and chat - Quick voice-to-text messages
🔍 Search queries - Faster than typing
📋 Long-form content - Reviews, feedback, descriptions
♿ Accessibility features - Essential for many users
🚗 Hands-free scenarios - When typing isn’t safe

Skip Voice Input For:

🔒 Sensitive data - Passwords, PINs, SSNs
📧 Format-specific fields - Emails, URLs, credit cards
🔢 Numeric codes - OTPs, account numbers
💻 Technical input - Code, command-line syntax

🚀 Performance Considerations

App Size Impact: 0 KB - Uses system APIs only

Runtime Performance:

Minimal memory usage
Lazy initialization (only when needed)
No background processes
Network call only during active recognition

Battery Impact:

Negligible - recognition happens on Google’s servers
No continuous listening (only when user taps mic)
Automatic cleanup after recognition

🎁 Quick Implementation Checklist

Before shipping voice input to production, verify:

✅ Mic icon only shows when isAvailable == true
🌐 Network connectivity is checked before launching
✍️ Input validation applied to voice results
📏 Max length limits enforced
🌍 Proper locale configuration
⚠️ User feedback for network errors
📱 Tested on devices without Google services
♿ Content descriptions added for accessibility
🎨 Visual feedback when mic is active (if custom UI)

💡 Final Thoughts

Voice input is a low-effort, high-impact feature that most apps overlook. With zero dependencies, no permissions, and minimal code, there’s little reason not to add it where appropriate.

The key differentiators:

Always check availability - hide the feature gracefully when unavailable
Validate network state - provide feedback when offline
Apply proper validation - treat voice input like any other input
Choose appropriate fields - not everything needs voice input

By following these guidelines, you’ll provide a professional, polished experience that sets your app apart.

That’s it! You now have a fully functional, production-ready speech-to-text component for Jetpack Compose. 🎉

Feel free to customize this implementation to fit your app’s specific needs. If you have questions or suggestions, reach out via my social handles! 😊

Happy coding! 🚀

Clickable Links in Jetpack Compose: AnnotatedString with Custom URL Handler

Tue, 11 Nov 2025 22:30:28 +0530

While building the onboarding screen for my app, I needed a simple text that read something like this:

The green hyperlinks are clickable

Pretty straightforward, right? Just a bit of text with two clickable links — Privacy Policy and Terms of Service.

But as I started implementing it, I realized: there isn’t a single complete guide explaining how to make part of a text clickable using AnnotatedString in Jetpack Compose — especially with the new LinkAnnotation API and a custom URL handler for better control.

So I’m writing this as both a reference for myself and for anyone else struggling with this tiny, under-documented detail.

Why Custom URL Handling?

By default, Compose can open links using the system browser. But what if you want:

Better UX with Chrome Custom Tabs (opens links in-app with smooth transitions)
Graceful fallbacks (handle cases where browsers aren’t installed)
Full control over how URLs are opened (analytics, deep links, etc.)

That’s exactly what we’ll implement.

Step-by-Step Implementation

1. Add the Browser Library

We’ll use Android Browser Library to implement Chrome Custom Tabs for a better link-opening experience.

Add this to your libs.versions.toml:

[versions]
browser = "1.8.0"

[libraries]
androidx-browser = { group = "androidx.browser", name = "browser", version.ref = "browser" }

Then add the dependency to your app’s build.gradle.kts:

dependencies {
    implementation(libs.androidx.browser)
}

Why Chrome Custom Tabs? Custom Tabs open web content inside your app with a smooth transition, pre-loaded browser engine, and shared cookies/sessions — all without leaving your app’s context.

2. Create a Custom URL Handler

This function handles opening URLs with three layers of fallback:

fun urlHandler(url: String, context: Context) {
    try {
        // First: Try Chrome Custom Tabs (best UX)
        val customTabsIntent = CustomTabsIntent.Builder().build()
        customTabsIntent.launchUrl(context, Uri.parse(url))
    } catch (e: ActivityNotFoundException) {
        try {
            // Second: Fallback to system browser
            val intent = Intent(Intent.ACTION_VIEW, Uri.parse(url))
            context.startActivity(intent)
        } catch (e: Exception) {
            // Third: Show toast if no browser exists
            Toast.makeText(
                context,
                "Browser not installed! visit: $url",
                Toast.LENGTH_LONG
            ).show()
        }
    } catch (e: Exception) {
        e.printStackTrace()
        Toast.makeText(
            context,
            "Unable to open link! visit: $url",
            Toast.LENGTH_SHORT
        ).show()
    }
}

How it works:

Chrome Custom Tabs (preferred): Opens in-app with native feel
System Browser (fallback): Opens in the default browser if Custom Tabs fail
Toast Message (last resort): Shows URL if no browser is available

This ensures your app never crashes when opening links, even on devices without browsers.

3. Building the Clickable Text Component

Now let’s create the actual composable with clickable links.

@OptIn(ExperimentalTextApi::class)
@Composable
internal fun TermsAndCondition() {
    val context = LocalContext.current

    // Define how links should behave when clicked
    val linkInteractionListener = LinkInteractionListener {
        urlHandler((it as LinkAnnotation.Url).url, context)
    }

    // Define link styling (color + underline)
    val linkStyle = TextLinkStyles(
        SpanStyle(
            color = DGreen,
            textDecoration = TextDecoration.Underline
        )
    )

    // Create Privacy Policy link annotation
    val privacyPolicy = LinkAnnotation.Url(
        url = URLS.PRIVACY,
        styles = linkStyle,
        linkInteractionListener = linkInteractionListener
    )

    // Create Terms of Service link annotation
    val toc = LinkAnnotation.Url(
        url = URLS.TOC,
        styles = linkStyle,
        linkInteractionListener = linkInteractionListener
    )

    // Helper functions for reusable link text (supports localization!)
    @Composable
    fun AnnotatedString.Builder.privacyLink() {
        withLink(privacyPolicy) {
            append(stringResource(id = R.string.privacy_policy))
        }
    }

    @Composable
    fun AnnotatedString.Builder.tocLink() {
        withLink(toc) {
            append(stringResource(id = R.string.terms_of_service))
        }
    }

    // Build the complete annotated string with mixed text + links
    val annotatedString = buildAnnotatedString {
        append("Read ")
        privacyLink()  // Clickable Privacy Policy
        append(" and tap on `")
        withStyle(style = SpanStyle(fontWeight = FontWeight.Bold)) {
            append("Agree and Continue")
        }
        append("` to accept the ")
        tocLink()  // Clickable Terms of Service
    }

    Text(
        text = annotatedString,
        style = PannaiTheme.typography.semiBold12.copy(
            color = LGray,
            textAlign = TextAlign.Center
        ),
        modifier = Modifier.fillMaxWidth(0.8f),
    )
}

Breaking Down the Code

LinkInteractionListener

val linkInteractionListener = LinkInteractionListener {
    urlHandler((it as LinkAnnotation.Url).url, context)
}

This listener gets triggered when any link is clicked
It extracts the URL from the LinkAnnotation.Url object
Passes it to our custom urlHandler() for controlled opening

LinkAnnotation.Url

val privacyPolicy = LinkAnnotation.Url(
    url = URLS.PRIVACY,
    styles = linkStyle,
    linkInteractionListener = linkInteractionListener
)

url: The actual link destination
styles: How the link looks (color, underline, etc.)
linkInteractionListener: What happens when clicked

This is the new Compose way of handling links (replaces older pushStringAnnotation approach).

Helper Functions for Localization

@Composable
fun AnnotatedString.Builder.privacyLink() {
    withLink(privacyPolicy) {
        append(stringResource(id = R.string.privacy_policy))
    }
}

Why helper functions? By using stringResource(), the link text automatically updates based on user’s language. This makes your code cleaner, reusable, and supports multi-language apps without duplicating logic.

Building the Final Text

val annotatedString = buildAnnotatedString {
    append("Read ")
    privacyLink()  // This part is clickable!
    append(" and tap on `")
    withStyle(style = SpanStyle(fontWeight = FontWeight.Bold)) {
        append("Agree and Continue")
    }
    append("` to accept the ")
    tocLink()  // This part is also clickable!
}

This combines regular text + clickable links + styled text in one component. withLink() wraps text and makes it interactive, while withStyle() applies visual formatting without making it clickable.

Key Takeaways

LinkAnnotation API is the modern way to create clickable links in Compose
Custom URL handler gives you full control over how links open
Chrome Custom Tabs provides better UX than default browser
Graceful fallbacks prevent app crashes on edge cases
Helper functions + stringResource make your code localization-ready

Why This Approach is Better

Compared to older methods using pushStringAnnotation, this approach:

Type-safe: LinkAnnotation is strongly typed
Easier styling: Direct style application per link
Better separation: Link logic separate from text building
Localization-friendly: Works seamlessly with multi-language apps

Thanks for reading! If you found this helpful, feel free to reach out via my social handles.