rememberMaterialInstance

Creates and manages a MaterialInstance from a Material. The instance is destroyed when this leaves the composition.

Accepts a nullable material so it chains directly off rememberMaterial, which returns null while loading; the result is null exactly while material is null. Primitives accept a nullable material and simply don't render until it arrives, so the whole chain needs no unwrapping:

val mat = rememberMaterial { Res.readBytes("files/materials/lit_color.filamat") }
Cube(material = rememberMaterialInstance(mat))   // renders once the material loads

Parameters

Creates a MaterialInstance and (re-)applies configure declaratively — the imperative createInstance() + setParameter(...) + dispose dance done for you. The instance is built once per material; configure runs once on creation and again whenever any value in keys changes, so parameters track Compose state without an onUpdate/SideEffect. The instance is destroyed when this leaves the composition.

Accepts a nullable material so it chains directly off rememberMaterial (null while loading); the result is null exactly while material is null, and primitives accept a nullable material:

val mat = rememberMaterial { Res.readBytes("files/materials/lit_color.filamat") }
val mi  = rememberMaterialInstance(mat, color) { setParameter("baseColor", color) }
Cube(material = mi)

Because the same instance is updated in place (never swapped), it is safe to keep referenced by a renderable while keys change — unlike allocating a fresh instance per colour, which can crash the render thread mid-frame (see docs/compose/materials.md).

Parameters