aldefy/compose-skill / skills/compose-expert
compose-expert
UnverifiedCompose and Compose Multiplatform expert for UI development across Android, Desktop, iOS, and Web. Use whenever the user mentions Compose APIs (@Composable, remember, LaunchedEffect, NavHost, MaterialTheme, LazyColumn, Modifier, recomposition), Compose Multiplatform (commonMain, expect/actual, Res.*, ComposeUIViewController, UIKitView, ComposeViewport), Android TV (tv-material, D-pad, focus, Carousel), Material 3 motion, atomic design systems, design-to-code workflows, Paging 3, or navigation. Activates Review Mode on GitHub PR URLs and review phrases ("review this PR", "what's wrong with this"). Auto-detects Compose projects on session_start. Backed by actual androidx/androidx and JetBrains/compose-multiplatform-core source receipts. See "## When this skill applies" in SKILL.md for the full trigger surface.
references/composition-locals.md
View on GitHub# CompositionLocals: Implicit Data Passing in Jetpack Compose
CompositionLocals provide a way to pass data implicitly down the composition tree without threading it through every function parameter. They're analogous to SwiftUI's `@Environment`.
## What Are CompositionLocals?
A CompositionLocal is a slot in the composition that holds a value accessible to any descendant composable without explicit parameter passing. Values are provided using `CompositionLocalProvider` and accessed via `current`.
```kotlin verify
// name: composition-local-provider-overrides-default
// repeat: 3
// assert: text = "Dark"
// assert-not: text = "Light"
val localAppTheme = compositionLocalOf { "Light" }
@Composable
fun Subject() {
CompositionLocalProvider(localAppTheme provides "Dark") {
DescendantComposable() // Can access "Dark" via localAppTheme.current
}
}
@Composable
fun DescendantComposable() {
Text(localAppTheme.current) // Reads "Dark"
}
```
**Source:** `androidx/compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/CompositionLocal.kt`
## compositionLocalOf vs staticCompositionLocalOf
The key difference is **when recomposition is triggered** when a value changes.
### compositionLocalOf
Causes recomposition of all descendants when the value changes. Use when children genuinely depend on the value.
```kotlin
val LocalUserPreferences = compositionLocalOf { UserPreferences() }
```
**Recomposition behavior:** All consumers recompose.
### staticCompositionLocalOf
No recomposition of descendants; only the direct reader is affected. Use when you're **confident descendants don't depend on updates**, or updates are infrequent.
```kotlin
val LocalAppVersion = staticCompositionLocalOf { "1.0.0" }
```
**⚠️ Pitfall:** If a child reads `LocalAppVersion.current` and expects updates, you'll get stale data. Only use for truly static configuration.
### compositionLocalWithComputedDefaultOf
Introduced for computed default values. The lambda is called each time the value is read when no provider is active.
```kotlin
val LocalResources = compositionLocalWithComputedDefaultOf { context.resources }
```
This is more efficient than `compositionLocalOf { lazy { ... } }` because it avoids capturing state unnecessarily.
## Built-In CompositionLocals
The Compose runtime and UI libraries provide standard locals:
| Local | Type | Purpose |
|-------|------|---------|
| `LocalContext` | `Context` | Android Context (requires AndroidCompositionLocals) |
| `LocalConfiguration` | `Configuration` | Screen size, orientation, density |
| `LocalDensity` | `Density` | Pixel density for dp/px conversion |
| `LocalLayoutDirection` | `LayoutDirection` | LTR/RTL directionality |
| `LocalView` | `View` | Underlying Android View (if available) |
| `LocalLifecycleOwner` | `LifecycleOwner` | Activity/Fragment lifecycle |
| `LocalSavedStateRegistryOwner` | `SavedStateRegistryOwner` | For state persistence |
**Source:** `androidx/compose/ui/ui/src/androidMain/kotlin/androidx/compose/ui/platform/AndroidCompositionLocals.android.kt`
```kotlin
@Composable
fun MyComposable() {
val context = LocalContext.current
val density = LocalDensity.current
val config = LocalConfiguration.current
Text("Screen width: ${config.screenWidthDp}dp")
}
```
## Providing Values with CompositionLocalProvider
Provide one or multiple local values:
```kotlin
// Single local
CompositionLocalProvider(LocalUserPreferences provides user) {
Content()
}
// Multiple locals
CompositionLocalProvider(
LocalUserPreferences provides user,
LocalTheme provides darkTheme,
LocalLanguage provides "en"
) {
Content()
}
```
Values are **scoped** to descendants only:
```kotlin
CompositionLocalProvider(LocalUserPreferences provides userA) {
ComponentA() // Sees userA
CompositionLocalProvider(LocalUserPreferences provides userB) {
ComponentB() // Sees userB (overrides)
}
ComponentC() // Sees userA (original)
}
```
## Creating Custom CompositionLocals
Create locals at top level, outside composable functions:
```kotlin
data class AppTheme(val isDark: Boolean, val colors: Colors)
val LocalAppTheme = compositionLocalOf<AppTheme> {
error("AppTheme not provided")
}
// For nullable defaults
val LocalOptionalUser = compositionLocalOf<User?> { null }
```
**When to create a CompositionLocal:**
- Value is needed by many descendants
- Threading it as a parameter creates "prop drilling"
- Value is configuration-like (theme, locale, permissions)
**When NOT to use CompositionLocal:**
- Only 1–2 levels of composables need it → use parameters
- Value changes frequently and children need precise control → use State/ViewModel
- It's a dependency that should be testable → prefer parameters or dependency injection
## Testing with CompositionLocals
Provide test doubles to avoid real implementations:
```kotlin
@Composable
fun MyScreen() {
val user = LocalUserRepository.current
Text(user.name)
}
// In test
@Test
fun testMyScreen() {
composeRule.setContent {
CompositionLocalProvider(
LocalUserRepository provides FakeUserRepository(User("Test User"))
) {
MyScreen()
}
}
composeRule.onNodeWithText("Test User").assertExists()
}
```
## Anti-Patterns
### ✗ Using CompositionLocal as Generic Dependency Injection
```kotlin
// Bad: obscures dependencies, hard to test
val LocalEverything = compositionLocalOf { AppContainer() }
@Composable
fun MyScreen() {
val container = LocalEverything.current
val repo = container.userRepo
val cache = container.cache
}
```
**Better:** Provide specific locals or pass dependencies as parameters.
### ✗ Reading LocalContext Repeatedly
```kotlin
// Inefficient: reads on every recomposition
@Composable
fun MyComposable() {
val context = LocalContext.current // Reading repeatedly
// ...
}
```
**Better:** Read once outside the lambda or cache in remember:
```kotlin
@Composable
fun MyComposable() {
val context = LocalContext.current
val effect = remember(context) { /* use context */ }
}
```
### ✗ Storing Mutable State in CompositionLocal
```kotlin
// Bad: state changes won't trigger recomposition properly
val LocalCounter = compositionLocalOf { mutableStateOf(0) }
```
**Better:** Store the State in a parent composable and provide the value, not the State:
```kotlin
val LocalCount = compositionLocalOf { 0 }
@Composable
fun Parent() {
var count by remember { mutableStateOf(0) }
CompositionLocalProvider(LocalCount provides count) {
Child()
}
}
```
## Key Takeaways
1. Use `compositionLocalOf` for values that children read and depend on updates
2. Use `staticCompositionLocalOf` only for truly static values
3. Prefer parameters over CompositionLocals unless you have significant nesting
4. Always provide a sensible error default or nullable type
5. Test by providing fake implementations via `CompositionLocalProvider`
6. CompositionLocals are not a replacement for proper architecture — use them for configuration and environment data, not general dependency injection
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |