0
# Resource Loading
1

2
Multiplatform resource loading system with support for strings, images, fonts, and pluralization, including localization and resource qualification for building internationalized applications.
3

4
## Capabilities
5

6
### String Resources
7

8
Load and format string resources with localization support.
9

10
```kotlin { .api }
11
/**
12
 * Load a string resource in a Composable context
13
 * @param resource String resource to load
14
 * @return Localized string value
15
 */
16
@ExperimentalResourceApi
17
@Composable
18
fun stringResource(resource: StringResource): String
19

20
/**
21
 * Load a formatted string resource with arguments in a Composable context
22
 * @param resource String resource to load
23
 * @param formatArgs Arguments for string formatting
24
 * @return Formatted localized string value
25
 */
26
@ExperimentalResourceApi
27
@Composable
28
fun stringResource(resource: StringResource, vararg formatArgs: Any): String
29

30
/**
31
 * Load a string resource outside of Composable context
32
 * @param resource String resource to load
33
 * @return Localized string value
34
 */
35
@ExperimentalResourceApi
36
suspend fun getString(resource: StringResource): String
37

38
/**
39
 * Load a string resource with specific environment context
40
 * @param environment Resource environment for qualification
41
 * @param resource String resource to load
42
 * @return Localized string value
43
 */
44
@ExperimentalResourceApi
45
suspend fun getString(environment: ResourceEnvironment, resource: StringResource): String
46
```
47

48
**Usage Examples:**
49

50
```kotlin
51
import org.jetbrains.compose.resources.*
52

53
@OptIn(ExperimentalResourceApi::class)
54
@Composable
55
fun WelcomeScreen() {
56
    Column {
57
        // Simple string resource
58
        Text(stringResource(Res.string.welcome_title))
59
        
60
        // Formatted string resource
61
        val userName = "John"
62
        Text(stringResource(Res.string.welcome_message, userName))
63
        
64
        // Load string outside composable
65
        LaunchedEffect(Unit) {
66
            val loadedString = getString(Res.string.loading_message)
67
            println(loadedString)
68
        }
69
    }
70
}
71
```
72

73
### Plural String Resources
74

75
Handle pluralization-aware string resources for different quantity contexts.
76

77
```kotlin { .api }
78
/**
79
 * Load a plural string resource based on quantity in Composable context
80
 * @param resource Plural string resource to load
81
 * @param quantity Quantity to determine plural form
82
 * @return Appropriate plural form of the string
83
 */
84
@ExperimentalResourceApi
85
@Composable
86
fun pluralStringResource(resource: PluralStringResource, quantity: Int): String
87

88
/**
89
 * Load a formatted plural string resource with arguments in Composable context
90
 * @param resource Plural string resource to load
91
 * @param quantity Quantity to determine plural form
92
 * @param formatArgs Arguments for string formatting
93
 * @return Formatted plural form of the string
94
 */
95
@ExperimentalResourceApi
96
@Composable
97
fun pluralStringResource(resource: PluralStringResource, quantity: Int, vararg formatArgs: Any): String
98

99
/**
100
 * Load a plural string resource outside of Composable context
101
 * @param resource Plural string resource to load
102
 * @param quantity Quantity to determine plural form
103
 * @return Appropriate plural form of the string
104
 */
105
@ExperimentalResourceApi
106
suspend fun getPluralString(resource: PluralStringResource, quantity: Int): String
107
```
108

109
**Usage Examples:**
110

111
```kotlin
112
@OptIn(ExperimentalResourceApi::class)
113
@Composable
114
fun ItemCounter(itemCount: Int) {
115
    // Handles "1 item" vs "5 items" automatically
116
    Text(pluralStringResource(Res.plurals.item_count, itemCount, itemCount))
117
}
118
```
119

120
### Image and Drawable Resources
121

122
Load images, vectors, and drawable resources with automatic format detection.
123

124
```kotlin { .api }
125
/**
126
 * Load a drawable resource as a Painter (automatically detects format)
127
 * @param resource Drawable resource to load
128
 * @return Painter for the resource
129
 */
130
@ExperimentalResourceApi
131
@Composable
132
fun painterResource(resource: DrawableResource): Painter
133

134
/**
135
 * Load a drawable resource as an ImageBitmap
136
 * @param resource Drawable resource to load
137
 * @return ImageBitmap representation
138
 */
139
@ExperimentalResourceApi
140
@Composable
141
fun imageResource(resource: DrawableResource): ImageBitmap
142

143
/**
144
 * Load a vector drawable resource as an ImageVector
145
 * @param resource Drawable resource to load (must be vector format)
146
 * @return ImageVector representation
147
 */
148
@ExperimentalResourceApi
149
@Composable
150
fun vectorResource(resource: DrawableResource): ImageVector
151

152
/**
153
 * Load drawable resource bytes with environment context
154
 * @param environment Resource environment for qualification
155
 * @param resource Drawable resource to load
156
 * @return Raw bytes of the drawable resource
157
 */
158
@ExperimentalResourceApi
159
suspend fun getDrawableResourceBytes(environment: ResourceEnvironment, resource: DrawableResource): ByteArray
160
```
161

162
**Usage Examples:**
163

164
```kotlin
165
@OptIn(ExperimentalResourceApi::class)
166
@Composable
167
fun ImageGallery() {
168
    Column {
169
        // Load as Painter (recommended for most use cases)
170
        Image(
171
            painter = painterResource(Res.drawable.logo),
172
            contentDescription = "App Logo",
173
            modifier = Modifier.size(64.dp)
174
        )
175
        
176
        // Load as ImageBitmap for custom drawing
177
        val imageBitmap = imageResource(Res.drawable.pattern)
178
        Canvas(modifier = Modifier.size(100.dp)) {
179
            drawImage(imageBitmap)
180
        }
181
        
182
        // Load vector specifically
183
        Icon(
184
            imageVector = vectorResource(Res.drawable.ic_star),
185
            contentDescription = "Star Icon"
186
        )
187
    }
188
}
189
```
190

191
### Font Resources
192

193
Load font resources for typography with font weight and style variations.
194

195
```kotlin { .api }
196
/**
197
 * Create a Font from a font resource
198
 * @param resource Font resource to load
199
 * @param weight Font weight
200
 * @param style Font style
201
 * @param variationSettings Font variation settings
202
 * @return Font object for use in typography
203
 */
204
@ExperimentalResourceApi
205
@Composable
206
expect fun Font(
207
    resource: FontResource,
208
    weight: FontWeight = FontWeight.Normal,
209
    style: FontStyle = FontStyle.Normal,
210
    variationSettings: FontVariation.Settings = FontVariation.Settings()
211
): Font
212

213
/**
214
 * Load font resource bytes with environment context
215
 * @param environment Resource environment for qualification
216
 * @param resource Font resource to load
217
 * @return Raw bytes of the font resource
218
 */
219
@ExperimentalResourceApi
220
suspend fun getFontResourceBytes(environment: ResourceEnvironment, resource: FontResource): ByteArray
221
```
222

223
**Usage Examples:**
224

225
```kotlin
226
@OptIn(ExperimentalResourceApi::class)
227
@Composable
228
fun CustomTypography() {
229
    val customFont = Font(
230
        resource = Res.font.roboto_bold,
231
        weight = FontWeight.Bold
232
    )
233
    
234
    val fontFamily = FontFamily(customFont)
235
    
236
    Text(
237
        text = "Custom Font Text",
238
        fontFamily = fontFamily,
239
        fontSize = 18.sp
240
    )
241
}
242
```
243

244
### Resource Environment
245

246
Manage resource qualification and localization contexts.
247

248
```kotlin { .api }
249
/**
250
 * Get the current resource environment in Composable context
251
 * @return Current ResourceEnvironment with system qualifiers
252
 */
253
@ExperimentalResourceApi
254
@Composable
255
fun rememberResourceEnvironment(): ResourceEnvironment
256

257
/**
258
 * Get the system resource environment outside Composable context
259
 * @return System ResourceEnvironment with default qualifiers
260
 */
261
@ExperimentalResourceApi
262
fun getSystemResourceEnvironment(): ResourceEnvironment
263

264
/**
265
 * Resource environment containing qualification information for resource loading
266
 */
267
@ExperimentalResourceApi
268
class ResourceEnvironment {
269
    // Implementation details are internal
270
}
271
```
272

273
**Usage Examples:**
274

275
```kotlin
276
@OptIn(ExperimentalResourceApi::class)
277
@Composable
278
fun LocalizedContent() {
279
    val environment = rememberResourceEnvironment()
280
    
281
    LaunchedEffect(environment) {
282
        // Load resources with specific environment
283
        val localizedString = getString(environment, Res.string.title)
284
        println("Current locale string: $localizedString")
285
    }
286
}
287
```
288

289
### Resource Types
290

291
Core resource type definitions for type-safe resource access.
292

293
```kotlin { .api }
294
/**
295
 * Represents a string resource
296
 */
297
@ExperimentalResourceApi
298
class StringResource
299

300
/**
301
 * Represents a drawable/image resource
302
 */
303
@ExperimentalResourceApi
304
class DrawableResource
305

306
/**
307
 * Represents a font resource
308
 */
309
@ExperimentalResourceApi
310
class FontResource
311

312
/**
313
 * Represents a plural string resource with quantity-based forms
314
 */
315
@ExperimentalResourceApi
316
class PluralStringResource
317
```
318

319
### Resource Qualifiers (Internal API)
320

321
Internal qualifier system for resource matching (advanced usage).
322

323
```kotlin { .api }
324
@InternalResourceApi
325
class LanguageQualifier
326

327
@InternalResourceApi
328
class RegionQualifier
329

330
@InternalResourceApi
331
class ThemeQualifier
332

333
@InternalResourceApi
334
class DensityQualifier
335
```
336

337
**Note:** Internal APIs are subject to change and should not be used in production code.
338

339
### Resource Access Pattern
340

341
Resources are typically accessed through a generated `Res` object:
342

343
```kotlin
344
// Generated resource access
345
Res.string.welcome_message       // StringResource
346
Res.drawable.app_icon           // DrawableResource  
347
Res.font.custom_font           // FontResource
348
Res.plurals.item_count         // PluralStringResource
349
```
350

351
### Experimental API Note
352

353
All resource APIs are marked with `@ExperimentalResourceApi` and require opt-in:
354

355
```kotlin
356
@file:OptIn(ExperimentalResourceApi::class)
357
```
358

359
or at usage sites:
360

361
```kotlin
362
@OptIn(ExperimentalResourceApi::class)
363
@Composable
364
fun MyComposable() {
365
    // Resource usage
366
}
367
```