0
# Compose Multiplatform UI for WASM/JS
1

2
Compose Multiplatform UI for WASM/JS enables developers to create declarative user interfaces that run in web browsers using WebAssembly technology. This package provides the complete Compose UI toolkit optimized for WASM targets, including window management, UI components, resource handling, and browser integration capabilities.
3

4
## Package Information
5

6
- **Package Name**: org.jetbrains.compose.ui:ui-wasm-js
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Version**: 1.8.2
10
- **Target Platforms**: WebAssembly (WASM), JavaScript (JS)
11
- **Installation**: Add to your `build.gradle.kts`:
12

13
```kotlin
14
kotlin {
15
    wasmJs {
16
        moduleName = "your-app-name"
17
        browser()
18
        binaries.executable()
19
    }
20
}
21

22
dependencies {
23
    implementation(compose.runtime)
24
    implementation(compose.ui)
25
    implementation(compose.foundation)
26
    implementation(compose.material)
27
    implementation(compose.components.resources)
28
}
29
```
30

31
## Core Imports
32

33
```kotlin
34
// Window management
35
import androidx.compose.ui.window.CanvasBasedWindow
36
import androidx.compose.ui.ExperimentalComposeUiApi
37

38
// UI components
39
import androidx.compose.foundation.*
40
import androidx.compose.foundation.layout.*
41
import androidx.compose.material.*
42
import androidx.compose.runtime.*
43
import androidx.compose.ui.*
44

45
// Resources
46
import org.jetbrains.compose.resources.*
47
import org.jetbrains.compose.resources.ExperimentalResourceApi
48
```
49

50
## Basic Application Setup
51

52
```kotlin { .api }
53
@OptIn(ExperimentalComposeUiApi::class, ExperimentalResourceApi::class)
54
fun main() {
55
    configureWebResources {
56
        resourcePathMapping { path -> "./$path" }
57
    }
58
    CanvasBasedWindow("My App") {
59
        App()
60
    }
61
}
62

63
@Composable
64
fun App() {
65
    MaterialTheme {
66
        Surface {
67
            Text("Hello, Compose WASM!")
68
        }
69
    }
70
}
71
```
72

73
## Architecture Overview
74

75
Compose Multiplatform UI for WASM/JS is **not a standalone module** but part of the unified `compose.ui` multiplatform system. WASM support is achieved through:
76

77
- **Kotlin/Wasm compilation**: Uses `wasmJs` target with `wasmJsMain` source sets
78
- **Canvas-based rendering**: All UI renders to HTML5 Canvas via Skiko WASM runtime
79
- **Browser integration**: Direct access to browser APIs and web platform features
80
- **Resource system**: Optimized async loading for web deployment
81

82
## Core Capabilities
83

84
### Window Management and Application Lifecycle
85
Create and manage application windows with canvas-based rendering, handle application lifecycle events, and configure the main application entry point.
86

87
**Key APIs:**
88
```kotlin { .api }
89
fun CanvasBasedWindow(
90
    canvasElementId: String? = null,
91
    title: String = "Compose Application", 
92
    content: @Composable () -> Unit
93
)
94
```
95

96
[Window Management Documentation](window-management.md)
97

98
### UI Components and Layouts
99
Complete set of declarative UI components including layouts, text, images, buttons, and interactive elements. All standard Compose components work seamlessly with WASM targets.
100

101
**Key APIs:**
102
```kotlin { .api }
103
@Composable fun Column(modifier: Modifier = Modifier, content: @Composable ColumnScope.() -> Unit)
104
@Composable fun Row(modifier: Modifier = Modifier, content: @Composable RowScope.() -> Unit)  
105
@Composable fun Box(modifier: Modifier = Modifier, content: @Composable BoxScope.() -> Unit)
106
@Composable fun Text(text: String, modifier: Modifier = Modifier, style: TextStyle = LocalTextStyle.current)
107
@Composable fun Button(onClick: () -> Unit, modifier: Modifier = Modifier, content: @Composable RowScope.() -> Unit)
108
```
109

110
[UI Components Documentation](ui-components.md)
111

112
### Material Design System
113
Full Material Design component library with theming, colors, typography, and interactive components optimized for web deployment.
114

115
**Key APIs:**
116
```kotlin { .api }
117
@Composable fun MaterialTheme(
118
    colors: Colors = MaterialTheme.colors,
119
    typography: Typography = MaterialTheme.typography,
120
    shapes: Shapes = MaterialTheme.shapes,
121
    content: @Composable () -> Unit
122
)
123
@Composable fun Scaffold(
124
    modifier: Modifier = Modifier,
125
    topBar: @Composable () -> Unit = {},
126
    content: @Composable (PaddingValues) -> Unit
127
)
128
```
129

130
[Material Design Documentation](material-design.md)
131

132
### Resource Management
133
Asynchronous resource loading system for images, strings, fonts, and other assets with web-optimized caching and loading strategies.
134

135
**Key APIs:**
136
```kotlin { .api }
137
fun configureWebResources(configure: WebResourcesConfiguration.() -> Unit)
138
@Composable fun painterResource(resource: DrawableResource): Painter
139
@Composable fun stringResource(resource: StringResource): String
140
```
141

142
[Resource Management Documentation](resource-management.md)
143

144
### Browser Integration and Platform APIs
145
Direct integration with browser APIs, system preferences detection, network operations, and JavaScript interoperability for platform-specific functionality.
146

147
**Key APIs:**
148
```kotlin { .api }
149
// Browser window access
150
val window: Window = kotlinx.browser.window
151
val document: Document = kotlinx.browser.document
152

153
// Platform detection
154
fun getCurrentPlatform(): String
155
fun getCurrentLanguage(): String
156
```
157

158
[Browser Integration Documentation](browser-integration.md)
159

160
### State Management and Reactivity
161
Compose runtime system for state management, side effects, and reactive programming patterns that work seamlessly with WASM execution model.
162

163
**Key APIs:**
164
```kotlin { .api }
165
@Composable fun <T> remember(calculation: () -> T): T
166
@Composable fun <T> mutableStateOf(value: T): MutableState<T>
167
@Composable fun LaunchedEffect(key1: Any?, block: suspend CoroutineScope.() -> Unit)
168
@Composable fun <T> State<T>.collectAsState(): State<T>
169
```
170

171
[State Management Documentation](state-management.md)
172

173
## Browser Compatibility
174

175
**Minimum Requirements:**
176
- Chrome 119+
177
- Firefox 120+  
178
- Safari 17+
179
- Edge 119+
180

181
**Required Features:**
182
- WebAssembly GC support
183
- WebAssembly Exception-Handling
184
- ES Modules support
185

186
## Performance Considerations
187

188
- **Single-threaded execution**: All operations run on the main thread
189
- **Memory management**: Manual GC triggering available for performance-critical scenarios
190
- **Bundle optimization**: Tree-shaking and code splitting supported
191
- **Async loading**: Resources load asynchronously to prevent blocking
192

193
## Development Workflow
194

195
1. **Project setup**: Configure Kotlin multiplatform with `wasmJs` target
196
2. **Dependencies**: Add Compose Multiplatform dependencies  
197
3. **Development**: Write Compose UI code using standard APIs
198
4. **Testing**: Use Compose testing framework for UI tests
199
5. **Building**: Generate WASM binary and JS loader
200
6. **Deployment**: Serve static files with WASM MIME types configured
201

202
## Distribution
203

204
WASM applications are distributed as:
205
- `.wasm` binary file containing compiled Kotlin code
206
- `.js` loader script for WASM initialization
207
- `index.html` entry point with canvas element
208
- Static resources (images, fonts, manifests)
209

210
## Error Handling
211

212
Common issues and solutions:
213
- **WASM loading failures**: Ensure proper MIME type configuration  
214
- **Canvas not found**: Verify canvas element ID matches application setup
215
- **Resource loading errors**: Check resource path configuration and CORS policies
216
- **Memory issues**: Monitor memory usage and implement proper cleanup