Styling text in Jetpack Compose sounds simple… until it isn’t. In this post, we’ll explore the limitations of AnnotatedString and how StyledString makes rich text way easier to manage. Let’s break it down 👇

📚 Table of Contents

1. Introduction: A Bold Word, a Link, and a Whole Lot of Trouble
2. AnnotatedString: Too Much Style, Not Enough Simplicity
3. Introducing StyledString: One API to Style Them All
4. StyledString Under the Hood: The Engine Behind the API
5. Final Thoughts

Introduction: A Bold Word, a Link, and a Whole Lot of Trouble

At first, you’ve got AnnotatedString, a SpanStyle, and everything feels smooth. You want to bold a word? Easy ✅. Underline something? No problem. It even feels kind of fun, especially when you’re building the whole string manually, like in the official docs.

But here’s the thing 🧠

That works great when you’re in full control of the string. The moment you’re dealing with real-world content: dynamic copy, localized text, paragraphs passed in from somewhere else, and you need to style just part of it?

Things get ugly. Fast.

Suddenly you’re tracking substrings, calculating indices, applying styles, and wiring up click listeners. All it takes is one change to the text, and your logic falls apart like a house of cards 🃏

All you wanted was to bold a word and make a link clickable. Now you’re knee-deep in boilerplate, praying nothing shifts.

In this post, I’ll walk through why AnnotatedString doesn’t scale well in real UIs, and introduce a tiny abstraction I built to fix that. It’s called StyledString💡And it does one thing really well:

Make text styling in Compose simple again.

AnnotatedString: Too Much Style, Not Enough Simplicity

Let’s give AnnotatedString some credit first. It’s a powerful tool 💪

You can create styled, clickable, interactive text using a single Text composable. Want to make one word bold and another act like a link? Totally possible. The API is flexible, low-level, and backed by the same rich text engine that powers Compose itself.

The problem is, it works best when you’re building the entire string manually.

Most examples in the docs look like this:

Pretty nice, right? But here’s where it gets tricky 👀

What if you have a full block of dynamic text, like a localized string or a sentence pulled from somewhere else, and you just want to style part of it?

Now you’re dealing with:

• Finding the substring you want to style
• Calculating start and end indices
• Manually adding styles or annotations
• Hoping the text never changes or everything will fall apart

And if you need multiple styles, like a bold word, a clickable email, and an underlined URL, dynamically, things get messy fast 🔥

At that point, buildAnnotatedString turns into a mix of brittle index math, repeated logic, and boilerplate that’s hard to read and even harder to maintain.

Sure, AnnotatedString is powerful. But when your text is dynamic and you just want to style parts of it? It stops being fun real quick.

Introducing StyledString: One API to Style Them All

After wrestling with AnnotatedString one too many times, I decided to build something better. Not a massive library or a full styling framework. Just a simple, Compose-friendly abstraction that solves one very specific problem.

Say hello to StyledString 👋

The goal is simple: let you define which parts of a string should be styled or clickable, without worrying about indexOf, addStyle, or AnnotatedString.Builder. You write the text, tell it which words to style, and what to do when clicked.

Here’s what it looks like in action:

That’s it. No manual text construction. No index math. No boilerplate.

Just clean, readable, declarative styling that works with real-world text.

And because StyledString supports types like Simple, ClickableEmail, and ClickableUrl, it’s easy to extend and reuse across your app. You get clickable, styled text without giving up sanity or maintainability 🙏

StyledString Under the Hood: The Engine Behind the API

Let’s pop the hood and go step-by-step through how StyledString works 🧠

It may feel like magic 🪄 when you use StyledText in your UI, but behind the scenes it’s just a clean, composable-friendly architecture built to reduce styling pain without adding unnecessary complexity.

This section covers every part of the system, from how styles are described, to how they’re found, applied, and rendered on screen.

🧱 1. The Data Model: StyledString and ClickableStyleString

At the core of this entire utility is a sealed interface called StyledString. This is how we model pieces of text that should be styled in some way.

Every StyledString needs two pieces of info:

• highlightedText: the exact portion of the full text that should be styled
• style: the SpanStyle that defines how it should look (color, underline, font weight, etc.)

We then define a few specific types that implement this interface:

This one is purely visual, it changes how the text looks but doesn’t respond to clicks.

Then we introduce interactive types:

These do the same styling work, but also carry extra data (like the URL or email they should open when tapped). And importantly, they implement a second interface: ClickableStyleString.

This function is called once for each match of each StyledString.

Now let’s look at what it does:

If it’s a URL, we create a LinkAnnotation.Url, attach the style, and give it a click listener. addLink handles attaching that to the correct range of text.

We do similar but using LinkAnnotation.Clickable for emails:

And if the style is just visual (non-clickable), we apply a regular span:

This takes the full text and returns a list of starting indices for every match of the given substring.

Here’s how it works:

Quick early exit for empty substrings. Avoids weird edge cases.

Then we prepare for case-insensitive searches (if needed):

Now we iterate through the string, finding all matches:

We finally, return the results:

This keeps our styling logic flexible and resilient, whether we’re styling a word that appears once or a dozen times.

🧠 4. Building the AnnotatedString: rememberStyledAnnotationString

Here’s the function that brings it all together. It receives the full text and your StyledString list, and returns an AnnotatedString with all the styles applied.

We make sure to use rememberUpdatedState() to keep the click listener fresh:

Then we use remember to cache the work unless inputs change:

We start by appending the full unstyled text. Then for each StyledString, we find all matching locations and apply the style:

This loop is what lets the styling be dynamic and multi-target. You can pass any localized or runtime-generated string as fullText, and it will still apply styles correctly.

🧩 5. The Composable: StyledText

Finally, here’s the StyledText composable that ties everything together.

You pass in the full text, the styles, and optionally a click handler. Here’s what it does internally:

This calls the logic we just walked through. Which returns a styled AnnotatedString.

Then we render it:

This is what you will see in the preview:

✅ Wrap-Up: A Simple Engine with Clean Output

To summarize, we’ve built a fully reusable Compose utility that:

• Describes styling declaratively with StyledString
• Separates visual and clickable styles safely
• Applies spans and links using applyStyle
• Finds multiple matches with findAllOccurrences
• Assembles everything in a compose-stable way
• Wraps up in a clean API: StyledText

No indexOf, no brittle range logic, no need to copy and paste buildAnnotatedString boilerplate anymore.

Get the full solution here.

Final Thoughts 🎯

Jetpack Compose gives us a lot of power, but not always the most ergonomic tools out of the box. AnnotatedString is awesome for one-offs, but once your UI needs multiple styles, reused patterns, or dynamic click handling, it gets verbose fast.

That’s where StyledString comes in.

It doesn’t replace AnnotatedString, it wraps it, giving you a safer and clearer way to describe intent:

→ “Make this word bold”
→ “Make this phrase a link”
→ “Style every instance of this string”

You stop thinking about text offsets and span ranges and start thinking in terms of meaning. The result: cleaner code, less boilerplate, and a better developer experience 💆

🧩 Easy to Adopt

You don’t need to refactor your whole app to use StyledString.

Start by replacing one or two Text() elements with StyledText(). Replace your inline buildAnnotatedString { ... } blocks with a simple list of StyledString.Simple or ClickableUrl.

That’s it. You’re in ✨

🛠️ Easy to Extend

Got more use cases?

• Style #hashtags?
• Handle @mentions?
• Auto-detect phone numbers?
• Add icons or background highlights?

Just create a new data class that implements StyledString, and handle it inside applyStyle(). The rest of the system stays untouched.

This kind of separation makes your text logic modular, testable, and adaptable to future design or business needs.

If you come up with something interesting, don’t forget to share it in the comments section 😉

🫱 Your Turn

Now that you’ve seen how it works (and how little code it really takes), go ahead and try it in your next Compose screen. No more fiddly AnnotatedString.Builder code. No more duplicated span logic. Just describe what you want, and let StyledText take care of the rest.

Make text styling in Compose simple again 😎

🤝 Thanks for reading

If you end up using StyledString in your project, let me know! Always cool to see where these little patterns land in the real world 👀

Thanks for reading! If you found this helpful, consider sharing it with a fellow dev, clapping or dropping a comment. It helps a lot ✌️

This article was previously published on proandroiddev.com.