0
# Compose Web HTML
1

2
Compose Web HTML is a Kotlin library that enables building reactive web user interfaces using a declarative, type-safe HTML DSL. It provides comprehensive HTML element support, modern CSS styling capabilities, robust event handling, and full SVG integration, all with Kotlin's type safety and Compose's reactivity model.
3

4
## Package Information
5

6
- **Package Name**: org.jetbrains.compose.html:html-core
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Target**: JavaScript (Kotlin/JS)
10
- **Installation**: Add to Gradle dependencies: `implementation("org.jetbrains.compose.html:html-core:1.8.2")`
11

12
## Core Imports
13

14
```kotlin
15
import org.jetbrains.compose.web.*
16
import org.jetbrains.compose.web.dom.*
17
import org.jetbrains.compose.web.css.*
18
import org.jetbrains.compose.web.events.*
19
```
20

21
## Basic Usage
22

23
```kotlin
24
import org.jetbrains.compose.web.*
25
import org.jetbrains.compose.web.dom.*
26
import org.jetbrains.compose.web.css.*
27

28
fun main() {
29
    // Mount composition to a DOM element
30
    renderComposable(rootElementId = "root") {
31
        Div({
32
            style {
33
                display(DisplayStyle.Flex)
34
                flexDirection(FlexDirection.Column)
35
                gap(16.px)
36
                padding(20.px)
37
            }
38
        }) {
39
            H1 { Text("Welcome to Compose Web") }
40
            
41
            P {
42
                Text("Build reactive web UIs with type-safe HTML DSL")
43
            }
44
            
45
            Button({
46
                onClick { event ->
47
                    console.log("Button clicked!")
48
                }
49
            }) {
50
                Text("Click Me")
51
            }
52
        }
53
    }
54
}
55
```
56

57
## Architecture
58

59
Compose Web HTML is built around several key components:
60

61
- **Composition System**: Integration with Compose runtime for reactive UI updates and state management
62
- **HTML DSL**: Type-safe builders for all HTML elements with proper attribute validation
63
- **CSS System**: Comprehensive CSS property support with type-safe units, colors, and modern layout features
64
- **Event Handling**: Synthetic event system that wraps native browser events with type safety
65
- **DOM Integration**: Direct DOM manipulation through Compose's applier system for optimal performance
66
- **Controlled/Uncontrolled**: Flexible input handling supporting both Compose-managed and browser-managed state
67

68
## Capabilities
69

70
### HTML Elements
71

72
Complete HTML element support including document structure, typography, forms, tables, media, and utility elements. All elements support attributes, styling, and event handling.
73

74
```kotlin { .api }
75
// Container elements
76
fun Div(attrs: AttrBuilderContext<HTMLDivElement>? = null, content: ContentBuilder<HTMLDivElement>? = null)
77
fun Span(attrs: AttrBuilderContext<HTMLSpanElement>? = null, content: ContentBuilder<HTMLSpanElement>? = null)
78

79
// Typography
80
fun H1(attrs: AttrBuilderContext<HTMLHeadingElement>? = null, content: ContentBuilder<HTMLHeadingElement>? = null)
81
fun P(attrs: AttrBuilderContext<HTMLParagraphElement>? = null, content: ContentBuilder<HTMLParagraphElement>? = null)
82

83
// Forms
84
fun Input(type: InputType<String>, attrs: AttrBuilderContext<HTMLInputElement>? = null)
85
fun Button(attrs: AttrBuilderContext<HTMLButtonElement>? = null, content: ContentBuilder<HTMLButtonElement>? = null)
86

87
// Text content
88
fun Text(value: String)
89
```
90

91
[HTML Elements](./html-elements.md)
92

93
### CSS Styling
94

95
Modern CSS support with type-safe properties, units, colors, and layout systems including Flexbox and Grid. Supports both inline styles and stylesheet classes.
96

97
```kotlin { .api }
98
// Style application
99
fun style(builder: StyleScope.() -> Unit)
100

101
// Layout properties
102
fun StyleScope.display(value: DisplayStyle)
103
fun StyleScope.position(value: Position)
104
fun StyleScope.flexDirection(value: FlexDirection)
105
fun StyleScope.gridTemplateColumns(value: String)
106

107
// Box model
108
fun StyleScope.width(value: CSSNumeric)
109
fun StyleScope.margin(value: CSSNumeric)
110
fun StyleScope.padding(value: CSSNumeric)
111
fun StyleScope.border(width: CSSNumeric?, style: LineStyle?, color: CSSColorValue?)
112

113
// Typography
114
fun StyleScope.fontSize(value: CSSNumeric)
115
fun StyleScope.fontWeight(value: FontWeight)
116
fun StyleScope.color(value: CSSColorValue)
117

118
// Units and values
119
val Number.px: CSSNumeric
120
val Number.em: CSSNumeric
121
val Number.percent: CSSNumeric
122
```
123

124
[CSS Styling](./css-styling.md)
125

126
### Event Handling
127

128
Comprehensive event system with synthetic events for mouse, keyboard, touch, focus, form, and animation interactions. All events are type-safe and provide access to native event properties.
129

130
```kotlin { .api }
131
// Event listener scope (available in attrs blocks)
132
fun EventsListenerScope.onClick(listener: (SyntheticMouseEvent) -> Unit)
133
fun EventsListenerScope.onInput(listener: (SyntheticInputEvent) -> Unit)
134
fun EventsListenerScope.onKeyDown(listener: (SyntheticKeyboardEvent) -> Unit)
135
fun EventsListenerScope.onFocus(listener: (SyntheticFocusEvent) -> Unit)
136

137
// Synthetic event types
138
interface SyntheticMouseEvent : SyntheticEvent<MouseEvent>
139
interface SyntheticKeyboardEvent : SyntheticEvent<KeyboardEvent>
140
interface SyntheticInputEvent : SyntheticEvent<InputEvent>
141
interface SyntheticFocusEvent : SyntheticEvent<FocusEvent>
142
```
143

144
[Event Handling](./event-handling.md)
145

146
### Form Elements and Input Handling
147

148
Specialized form elements with type-safe input handling supporting both controlled and uncontrolled modes. Comprehensive input type support with validation attributes.
149

150
```kotlin { .api }
151
// Specialized input elements
152
fun TextInput(value: String? = null, attrs: AttrBuilderContext<HTMLInputElement>? = null)
153
fun NumberInput(value: Number? = null, min: Number? = null, max: Number? = null, attrs: AttrBuilderContext<HTMLInputElement>? = null)
154
fun CheckboxInput(checked: Boolean? = null, attrs: AttrBuilderContext<HTMLInputElement>? = null)
155
fun RadioInput(checked: Boolean? = null, attrs: AttrBuilderContext<HTMLInputElement>? = null)
156

157
// Form elements
158
fun Form(action: String? = null, attrs: AttrBuilderContext<HTMLFormElement>? = null, content: ContentBuilder<HTMLFormElement>? = null)
159
fun Select(attrs: AttrBuilderContext<HTMLSelectElement>? = null, multiple: Boolean = false, content: ContentBuilder<HTMLSelectElement>? = null)
160
fun TextArea(value: String? = null, attrs: AttrBuilderContext<HTMLTextAreaElement>? = null)
161

162
// Input types
163
sealed class InputType<T>
164
object InputType.Text : InputType<String>
165
object InputType.Number : InputType<String>
166
object InputType.Email : InputType<String>
167
object InputType.Password : InputType<String>
168
```
169

170
[Forms and Input Handling](./forms-inputs.md)
171

172
### SVG Support
173

174
Complete SVG element support for scalable graphics including shapes, text, gradients, effects, and animations. All SVG elements integrate with the same styling and event systems.
175

176
```kotlin { .api }
177
// SVG container
178
fun Svg(viewBox: String? = null, attrs: AttrBuilderContext<SVGElement>? = null, content: ContentBuilder<SVGElement>? = null)
179

180
// SVG shapes
181
fun Circle(cx: Number, cy: Number, r: Number, attrs: AttrBuilderContext<SVGElement>? = null, content: ContentBuilder<SVGElement>? = null)
182
fun Rect(x: Number, y: Number, width: Number, height: Number, attrs: AttrBuilderContext<SVGElement>? = null, content: ContentBuilder<SVGElement>? = null)
183
fun Path(d: String, attrs: AttrBuilderContext<SVGElement>? = null, content: ContentBuilder<SVGElement>? = null)
184

185
// SVG text
186
fun SvgText(text: String, x: Number? = null, y: Number? = null, attrs: AttrBuilderContext<SVGElement>? = null)
187

188
// SVG effects
189
fun LinearGradient(id: String? = null, attrs: AttrBuilderContext<SVGElement>? = null, content: ContentBuilder<SVGElement>? = null)
190
fun Filter(attrs: AttrBuilderContext<SVGElement>? = null, content: ContentBuilder<SVGElement>? = null)
191
```
192

193
[SVG Support](./svg-support.md)
194

195
### Composition and Rendering
196

197
Core composition functions for mounting and managing Compose Web applications in the browser DOM.
198

199
```kotlin { .api }
200
// Main composition functions
201
fun <TElement : Element> renderComposable(
202
    root: TElement,
203
    monotonicFrameClock: MonotonicFrameClock = DefaultMonotonicFrameClock,
204
    content: @Composable DOMScope<TElement>.() -> Unit
205
): Composition
206

207
fun renderComposable(
208
    rootElementId: String,
209
    content: @Composable DOMScope<Element>.() -> Unit
210
): Composition
211

212
fun renderComposableInBody(
213
    content: @Composable DOMScope<HTMLBodyElement>.() -> Unit
214
): Composition
215

216
// DOM scope interface
217
interface DOMScope<out TElement : Element> {
218
    val DisposableEffectScope.scopeElement: TElement
219
}
220
```
221

222
## Types
223

224
```kotlin { .api }
225
// Core type aliases
226
typealias AttrBuilderContext<T> = AttrsScope<T>.() -> Unit
227
typealias ContentBuilder<T> = @Composable ElementScope<T>.() -> Unit
228

229
// Attribute scope interfaces
230
interface AttrsScope<out TElement : Element>
231
interface EventsListenerScope
232

233
// CSS value types
234
interface CSSNumeric
235
interface CSSColorValue
236
interface StyleScope
237

238
// Element scopes
239
interface ElementScope<out TElement : Element>
240

241
// Annotations
242
@RequiresOptIn("This API is experimental and is likely to change in the future.")
243
annotation class ExperimentalComposeWebApi
244

245
@RequiresOptIn("This SVG API is experimental and is likely to change in the future.")
246
annotation class ExperimentalComposeWebSvgApi
247
```