Best practices for designing Jetpack Compose APIs

When building UIs with Jetpack Compose (or Compose Multiplatform), especially in apps where all of the UI is now written in Compose, one of the biggest challenges I’ve seen is how inconsistent things can get across teams.

Here are two examples from my past experience:

• PR reviews get stuck on the same comments over and over. I’ve been in reviews where half the discussion is just about the order of modifiers, or whether a parameter should be hoisted or not. These things matter, but it slows everyone down when the same points have to be raised repeatedly.
  
  

• Every engineer has a different idea of how to build a Compose component. Once I saw two engineers build a card/tile component in completely different ways. One passed all the state down, the other used CompositionLocal to read the state. Both worked, but it felt like two different approaches living in the same codebase. Both approaches had their own scalability and maintainability issues, we’ll cover it below.

Problems like these aren’t just technical, they’re also about the team and the time and effort put into building software. More time ends up being spent debating code style than shipping features. Alignment across large teams is also critical but harder to achieve, which is why onboarding new engineers can either be super painful or super smooth depending on whether patterns are clearly set. Having guidelines enforced in the codebase means engineers know at the time of writing what’s acceptable, and more importantly, why.

That’s what led me to write this post. These are the 5 most common mistakes I’ve seen people make (the ones I’ve caught in reviews many times), along with how to fix them. I’ll also show how to automate some of these checks with lint rules, so we don’t have to rely on manual review comments for every PR.

I’ve been building design systems in Compose for the past 4 years now. While my approach isn’t perfect, these are some of the learnings that have worked well for me and my teams. 

1. Correct usage and order of Modifier

The first thing that comes to mind is Modifier and its correct usage.

Modifiers let us customize the appearance, behavior, and layout of UI elements. For example, we can change size, padding, background color, or add scrolling capability to a composable. Modifiers are immutable, so if we chain multiple modifiers, a new instance is created each time. The order of chaining is important here because it affects the final output.

Here are some of the other guidelines that should be followed when using Modifiers.

• Always take modifier: Modifier = Modifier as the first optional parameter.

• Apply the modifier to the root layout of your composable.

• Don’t reuse the same modifier for multiple composables. (unless you want to introduce bugs! 😉)

• Chain modifiers in a logical order (e.g., padding → background → clickable), otherwise ripple effects may be incorrect or you may wonder, where did the padding go.

Read more here: modifier-paramater 

3. Prefer slot APIs for flexibility and customisation

A common mistake is overloading your composables with too many parameters. Instead, provide slots that let callers inject their own composables. Example: If you build a Button that only supports a label, later when the design team asks for an optional icon, you’ll have to change the API and break existing usages.

See the approach 1 below in code example. This approach is rigid. It also raises questions like: should the icon be a drawable, or a design system icon type? What if we need something else? With slots, we don’t have to anticipate every future requirement up front.

4. State Hoisting for Reusability

State hoisting in Jetpack Compose is a design pattern where the state of a composable is moved to its caller (parent). You should keep the state closest to where it is consumed. State hoisting allows the caller to manage state, making your components more reusable and testable.

Code Exmaple:
In this approach 1, the switch owns its own state, so we can’t control it externally.

In the approach 2, the parent manages state, and the component stays reusable. If an external event or a ui other than MySwitch wants to toggle it, now it is possible too.

5. Use Composition Locals Sparingly

I think, using Composition Locals in Compose, is like adding spices to a dish. You need just the right amount otherwise it’s ruined.

We should use Composition locals for truly global values such as colors and typography. The things that probably won't change throughout the app session. However, we should avoid overusing them. Even though Composition Locals help us pass data down the tree without having to go through every composable child, they hide dependencies, affect testability, and make debugging harder. This can sometimes make us wonder why the composables are behaving in a way that isn't clear from just looking at the code.

Automating Best Practices with Lint Rules

Catching these issues in code review works, but it’s repetitive and slows down development. A better approach is to automate them with lint rules. These rules were originally built by engineers at Twitter, and are now maintained in this repository Compose Rules by Nacho Lopez.

They work with Compose Multiplatform or Android projects, and can be added as a Detekt plugin. For example:

detekt-compose = { group = "io.nlopez.compose.rules", name = "detekt", version = ”0.4.27" }

Once enabled, they’ll flag things like:

• Wrong Modifier usage or order

• Mutable parameters in composables

• Missing state hoisting

• Overuse of CompositionLocal

• Poor slot API design

Here’s an example of usage in my project KRAIL: KRAIL App - PR #813 This way, engineers don’t have to manually catch these in every PR. The checks run automatically and give instant feedback during development.

By following these guidelines, I hope your Compose APIs will feel more scalable. You can read in detail about compose api guidelines in the doc from androidx repository: Compose Component API Guidelines