Modifiers

A Modifier decorates or augments a composable: its size and padding, its background, what happens when it is clicked, what it tells accessibility services. Modifiers chain, and the order of the chain matters.

#Using modifiers

Most composables take a Modifier as a parameter. A chain starts from Modifier() and each call adds an element:

void ArtistCard(const std::string& name) {
Row(Modifier()
.fillMaxWidth()
.clickable([] { /* open the artist */ })
.padding(16),
[&] {
Icon(Icons::Filled::Person, "", Modifier().size(40));
Spacer(Modifier().width(12));
Text(name, {.font = typography().titleMedium});
});
}

Modifiers are plain values: you can store them in variables, pass them around and build them conditionally.

Modifier base = Modifier().fillMaxWidth().padding(8);
Box(selected ? base.background(colorScheme().secondaryContainer, 12) : base);

#Order matters

Each element wraps everything after it in the chain. The first element is the outermost: it is measured first and draws around the rest. So the same elements in a different order give a different result:

// The whole 72 dp area is clickable, and the padding is inside the click area.
Box(Modifier().clickable([] {}).padding(16).size(40));

// Only the 40 dp box is clickable; the padding is outside it.
Box(Modifier().padding(16).clickable([] {}).size(40));

The same goes for backgrounds:

Box(Modifier().background(colorScheme().primaryContainer).padding(16).size(40));   // padding is colored
Box(Modifier().padding(16).background(colorScheme().primaryContainer).size(40));   // padding is not

Read a chain from left to right as "from the outside in".

#Common modifiers

#Size

All lengths are in dp.

#Padding and position

#Drawing

#Interaction

#Accessibility and tests

#Layout callbacks

#Scope modifiers

Some modifiers only make sense inside a particular parent, like Compose's scoped modifiers (RowScope.weight):

In C++ these are ordinary Modifier methods: the compiler won't stop you from using weight outside a Row or a Column, it just has no effect there.

Row(Modifier().fillMaxWidth(), [&] {
Text("Left", Modifier().weight(1));
Text("Right");
});

#Writing your own

#Combining modifiers

C++ has no extension functions, so a modifier of your own is a function that returns a chain. Join it to another chain with then:

Modifier cardSurface() {
return Modifier().shadow(2, RoundedCornerShape(16)).background(colorScheme().surfaceContainerLow, RoundedCornerShape(16)).padding(16);
}

void Note(const std::string& text) {
Box(Modifier().fillMaxWidth().then(cardSurface()), [&] { Text(text); });
}

A function that takes the chain to extend reads naturally, too: Modifier card(const Modifier& m = {}) { return m.padding(…); }.

#Changing measurement

layout measures the content through measure with the constraints you choose and returns this node's size; placeAt says where the content goes inside it:

// The content centered in a square as big as its longer side.
Modifier squareAround() {
return Modifier().layout([](const MeasureNext& measure, const Constraints& c, Offset& placeAt) {
Size content = measure(c.loosen());
float side = std::max(content.width, content.height);
placeAt = {(side - content.width) / 2, (side - content.height) / 2};
return c.constrain(Size{side, side});
});
}

#Custom drawing

drawBehind draws behind the content, drawWithContent around it. See Graphics.

Modifier underline(Color color) {
return Modifier().drawBehind([color](DrawScope& d) {
d.drawLine(color, {0, d.size().height}, {d.size().width, d.size().height}, 2);
});
}

#Modifier elements

Underneath, a modifier is a list of ModifierElements. An element can take part in measuring, drawing and input; then(std::make_shared<MyElement>(…)) adds one. This is a lower-level API, used by the library's own modifiers; the functions above cover most needs. If you write an element, implement equals so that a composable called with an equal modifier can still be skipped.

#See also

• Layouts: the parents scope modifiers work in.
• Phases: modifiers that read state while laying out or drawing.
• Gestures and Graphics for the interaction and drawing modifiers.