0
# UI Tooling Preview
1

2
Development-time preview support with parameter providers for IDE integration and composable function previewing during development, enabling rapid UI iteration and testing.
3

4
## Capabilities
5

6
### Preview Annotation
7

8
Mark composable functions or annotation classes for IDE preview rendering.
9

10
```kotlin { .api }
11
/**
12
 * Marks a composable function for IDE preview or creates a custom preview annotation
13
 * Can be applied to @Composable functions directly or to annotation classes for reusable preview configurations
14
 * Supports @Repeatable for multiple preview variations of the same composable
15
 */
16
@Target(AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.FUNCTION)
17
@Repeatable
18
annotation class Preview
19
```
20

21
**Usage Examples:**
22

23
```kotlin
24
import org.jetbrains.compose.ui.tooling.preview.*
25

26
// Basic preview
27
@Preview
28
@Composable
29
fun WelcomeScreenPreview() {
30
    WelcomeScreen()
31
}
32

33
// Multiple previews for the same composable
34
@Preview
35
@Composable
36
fun ButtonPreview() {
37
    MyButton("Click me")
38
}
39

40
@Preview
41
@Composable
42
fun ButtonDisabledPreview() {
43
    MyButton("Disabled", enabled = false)
44
}
45
```
46

47
### Custom Preview Annotations
48

49
Create reusable preview configurations using annotation classes.
50

51
```kotlin
52
// Define a custom preview annotation
53
@Preview
54
@Target(AnnotationTarget.FUNCTION)
55
annotation class DarkModePreview
56

57
@Preview
58
@Target(AnnotationTarget.FUNCTION)
59
annotation class LightModePreview
60

61
// Use custom preview annotations
62
@DarkModePreview
63
@Composable
64
fun CardDarkPreview() {
65
    DarkTheme {
66
        MyCard("Dark mode card")
67
    }
68
}
69

70
@LightModePreview
71
@Composable
72
fun CardLightPreview() {
73
    LightTheme {
74
        MyCard("Light mode card")
75
    }
76
}
77
```
78

79
### Preview Parameters
80

81
Provide dynamic data to preview functions using parameter providers.
82

83
```kotlin { .api }
84
/**
85
 * Injects parameter values into preview functions using a provider class
86
 * @param provider KClass that implements PreviewParameterProvider<T>
87
 * @param limit Maximum number of parameter values to use (default: unlimited)
88
 */
89
@Target(AnnotationTarget.VALUE_PARAMETER)
90
annotation class PreviewParameter(
91
    val provider: KClass<out PreviewParameterProvider<*>>,
92
    val limit: Int = Int.MAX_VALUE
93
)
94
```
95

96
**Usage Examples:**
97

98
```kotlin
99
// Define a parameter provider
100
class UserDataProvider : PreviewParameterProvider<User> {
101
    override val values = sequenceOf(
102
        User("John Doe", "john@example.com"),
103
        User("Jane Smith", "jane@example.com"),
104
        User("Bob Johnson", "bob@example.com")
105
    )
106
}
107

108
// Use parameter provider in preview
109
@Preview
110
@Composable
111
fun UserCardPreview(
112
    @PreviewParameter(UserDataProvider::class, limit = 2) user: User
113
) {
114
    UserCard(user)
115
}
116
```
117

118
### Preview Parameter Provider Interface
119

120
Interface for creating parameter providers that supply data to preview functions.
121

122
```kotlin { .api }
123
/**
124
 * Interface for providing parameter values to preview functions
125
 * @param T Type of parameter values provided
126
 */
127
expect interface PreviewParameterProvider<T> {
128
    /** Sequence of parameter values to provide to the preview function */
129
    val values: Sequence<T>
130
    
131
    /** Number of parameter values available (optional, defaults to values.count()) */
132
    val count: Int
133
}
134
```
135

136
**Implementation Examples:**
137

138
```kotlin
139
// Simple data provider
140
class ColorProvider : PreviewParameterProvider<Color> {
141
    override val values = sequenceOf(
142
        Color.Red,
143
        Color.Green, 
144
        Color.Blue,
145
        Color.Yellow
146
    )
147
}
148

149
// Complex data provider with calculated count
150
class ThemeDataProvider : PreviewParameterProvider<ThemeData> {
151
    override val values = sequenceOf(
152
        ThemeData("Light", Color.White, Color.Black),
153
        ThemeData("Dark", Color.Black, Color.White),
154
        ThemeData("Blue", Color.Blue, Color.White)
155
    )
156
    
157
    override val count: Int = 3
158
}
159

160
// Data class for theme data
161
data class ThemeData(
162
    val name: String,
163
    val backgroundColor: Color,
164
    val textColor: Color
165
)
166

167
// Preview using theme provider
168
@Preview
169
@Composable
170
fun ThemedButtonPreview(
171
    @PreviewParameter(ThemeDataProvider::class) theme: ThemeData
172
) {
173
    Surface(color = theme.backgroundColor) {
174
        Button(
175
            onClick = { },
176
            colors = ButtonDefaults.buttonColors(
177
                contentColor = theme.textColor
178
            )
179
        ) {
180
            Text("Button - ${theme.name} Theme")
181
        }
182
    }
183
}
184
```
185

186
### Advanced Preview Patterns
187

188
#### Boolean Parameter Provider
189

190
```kotlin
191
class BooleanProvider : PreviewParameterProvider<Boolean> {
192
    override val values = sequenceOf(true, false)
193
}
194

195
@Preview
196
@Composable
197
fun TogglePreview(
198
    @PreviewParameter(BooleanProvider::class) isEnabled: Boolean
199
) {
200
    Switch(
201
        checked = isEnabled,
202
        onCheckedChange = { }
203
    )
204
}
205
```
206

207
#### Size Variations Provider
208

209
```kotlin
210
class SizeProvider : PreviewParameterProvider<Dp> {
211
    override val values = sequenceOf(
212
        24.dp, 32.dp, 48.dp, 64.dp
213
    )
214
}
215

216
@Preview
217
@Composable
218
fun IconSizePreview(
219
    @PreviewParameter(SizeProvider::class) size: Dp
220
) {
221
    Icon(
222
        Icons.Default.Star,
223
        contentDescription = "Star",
224
        modifier = Modifier.size(size)
225
    )
226
}
227
```
228

229
#### Text Content Provider
230

231
```kotlin
232
class TextContentProvider : PreviewParameterProvider<String> {
233
    override val values = sequenceOf(
234
        "Short",
235
        "Medium length text",
236
        "Very long text that might wrap to multiple lines and test text overflow behavior"
237
    )
238
}
239

240
@Preview
241
@Composable
242
fun TextCardPreview(
243
    @PreviewParameter(TextContentProvider::class) text: String
244
) {
245
    Card(
246
        modifier = Modifier.width(200.dp)
247
    ) {
248
        Text(
249
            text = text,
250
            modifier = Modifier.padding(16.dp)
251
        )
252
    }
253
}
254
```
255

256
### Complex Data Providers
257

258
```kotlin
259
// User state provider
260
enum class UserState { LOADING, LOGGED_IN, LOGGED_OUT, ERROR }
261

262
class UserStateProvider : PreviewParameterProvider<UserState> {
263
    override val values = UserState.values().asSequence()
264
}
265

266
@Preview
267
@Composable
268
fun UserProfilePreview(
269
    @PreviewParameter(UserStateProvider::class) state: UserState
270
) {
271
    when (state) {
272
        UserState.LOADING -> LoadingScreen()
273
        UserState.LOGGED_IN -> ProfileScreen(sampleUser)
274
        UserState.LOGGED_OUT -> LoginScreen()
275
        UserState.ERROR -> ErrorScreen("Failed to load profile")
276
    }
277
}
278
```
279

280
### Multiple Parameter Providers
281

282
```kotlin
283
@Preview
284
@Composable
285
fun ComplexPreview(
286
    @PreviewParameter(ColorProvider::class) backgroundColor: Color,
287
    @PreviewParameter(BooleanProvider::class, limit = 1) isDarkMode: Boolean
288
) {
289
    Surface(
290
        color = backgroundColor,
291
        modifier = Modifier.size(100.dp)
292
    ) {
293
        Text(
294
            text = if (isDarkMode) "Dark" else "Light",
295
            color = if (isDarkMode) Color.White else Color.Black,
296
            modifier = Modifier.padding(16.dp)
297
        )
298
    }
299
}
300
```
301

302
### Preview Best Practices
303

304
#### Meaningful Preview Names
305
```kotlin
306
@Preview
307
@Composable
308
fun ProductCard_EmptyState_Preview() {
309
    ProductCard(product = null)
310
}
311

312
@Preview
313
@Composable
314
fun ProductCard_WithLongTitle_Preview() {
315
    ProductCard(product = Product(title = "Very Long Product Title That Might Wrap"))
316
}
317
```
318

319
#### State Variations
320
```kotlin
321
@Preview
322
@Composable
323
fun LoadingButton_Enabled_Preview() {
324
    LoadingButton(isLoading = false, enabled = true) { }
325
}
326

327
@Preview
328
@Composable
329
fun LoadingButton_Loading_Preview() {
330
    LoadingButton(isLoading = true, enabled = false) { }
331
}
332

333
@Preview
334
@Composable
335
fun LoadingButton_Disabled_Preview() {
336
    LoadingButton(isLoading = false, enabled = false) { }
337
}
338
```
339

340
### IDE Integration
341

342
Preview functions appear in compatible IDEs with visual previews:
343
- **Android Studio**: Full preview support with interactive mode
344
- **IntelliJ IDEA**: Preview rendering for Compose Multiplatform
345
- **Other IDEs**: Basic preview support where available
346

347
### Development Workflow
348

349
1. **Create Composables**: Build your UI components
350
2. **Add Previews**: Create preview functions to visualize components
351
3. **Use Parameters**: Test different states and data variations
352
4. **Iterate Rapidly**: Make changes and see results immediately in preview
353
5. **Test Edge Cases**: Use parameter providers to test various scenarios