Skip to content
AppDues
Log in
Contact salesSign up

Custom Modifiers in Jetpack Compose: Modifier.then, Modifier.composed, and Modifier.Node

Jetpack Compose modifiers let a component stay independent while still accepting outside customization. This guide compares the three main ways to build a reusable custom modifier, explains how chaining really works under the hood, and shows when the lower-level node approach is worth the extra structure.

Why custom modifiers matter

A modifier does more than set appearance. It is a reusable extension point: behavior is packaged once, then attached wherever needed without coupling the component to that behavior. The practical question is which construction API fits the behavior you need.

Modifier.then: simple chaining

Modifier.then is the chaining operator behind every modifier chain. Each call wraps the existing chain and the new element in a CombinedModifier, a two-part container holding an outer part and an inner part. The result is a left-leaning nested structure rather than a flat list, and its two traversal directions support different phases of the UI pipeline. Use this approach when a custom modifier only combines existing modifiers and needs no composable state. Protected module code0001 shows a composable helper built this way, and code0002 shows a typical three-step chain.

Modifier.composed: composable state with a cost

Modifier.composed wraps a composable lambda so the factory can call functions such as remember and keep state tied to that modifier instance. Internally it adds a ComposedModifier through then. That convenience has a price: a new subcomposition per instance, and when no composable call is used the modifier can lose skippability, forcing the chain to re-run on recomposition. Reserve it for cases that genuinely need composable state inside the factory. Protected modules code0005 and code0006 show the stateful factory and its internal construction.

Modifier.Node: separate description from worker

Modifier.Node, available since Compose UI 1.3.0, is the recommended route for stateful custom modifiers. It avoids a subcomposition per instance by separating two roles. The element is a stateless description of configuration; the node is a mutable, lifecycle-aware worker that holds state and implements the actual drawing, layout, or other logic. The element creates the node on first use, then updates the existing node in place when its configuration changes, which keeps allocations down and lets the node survive recomposition. Protected module code0007 shows a node holding a color and drawing a circle.

The factory and the equality contract

Correct equality is what makes reuse work. If the element reports a change when nothing meaningful changed, update runs unnecessarily and the performance benefit disappears. A data class is the simplest reliable way to get equals and hashCode right. The public factory then stays small: it attaches the element to the current chain with then, so callers use the custom modifier exactly like a built-in one. Protected module code0008 shows that factory shape.

Choosing between the three

Start with then for plain combinations. Reach for composed only when the factory truly needs composable calls. Choose Modifier.Node when the modifier is stateful, reused often, or appears in dynamic lists where subcomposition overhead adds up. A real-world illustration is a placeholder feature migrated from composed to Node to improve UI performance, linked below as a concrete example to study.

Which custom modifier API fits your case?
ApproachBest forState handlingMain trade-off
Modifier.thenCombining existing modifiersNo composable state of its ownSimplest and lightest; cannot hold instance state
Modifier.composedFactories needing composable callsState via composable functions in the lambdaSubcomposition per instance; can lose skippability when unused
Modifier.NodeStateful, reusable, performance-sensitive modifiersMutable node updated in placeMore structure: element, node, and factory

Based on the three APIs described in the guide; performance notes reflect the stated subcomposition and skippability behavior.

Frequently asked questions

When is Modifier.then enough for a custom modifier?

Use Modifier.then when you only need to chain existing modifiers. It builds a CombinedModifier pair and adds no composable state of its own.

What does Modifier.composed add, and what is its cost?

It lets the lambda call composable functions and hold instance state, but it creates a subcomposition per instance and can make the modifier non-skippable when no composable call is actually needed.

How should a Modifier.Node modifier be structured?

Split the work into a stateless element that describes configuration and a stateful node that holds mutable state and implements the drawing or layout logic. The element creates the node once and updates it in place when configuration changes.

Why do equals and hashCode matter for a modifier element?

Implement equals and hashCode correctly, for example with a data class. Otherwise update can run on every recomposition and the reuse benefit is lost.