0
# Compose Resources
1

2
Compose Resources provides comprehensive resource management for Compose Multiplatform applications. It enables type-safe access to images, strings, fonts, and drawable assets across Android, Desktop (JVM), iOS, Web (JS/Wasm), and Native (macOS) platforms with automatic locale selection, density-aware scaling, and environment-specific resource loading.
3

4
## Package Information
5

6
- **Package Name**: org.jetbrains.compose.components:components-resources
7
- **Package Type**: maven
8
- **Language**: Kotlin Multiplatform
9
- **Version**: 1.8.2
10
- **Installation**: Add to `build.gradle.kts`:
11
  ```kotlin
12
  implementation("org.jetbrains.compose.components:components-resources:1.8.2")
13
  ```
14

15
## Core Imports
16

17
```kotlin
18
import org.jetbrains.compose.resources.*
19
import androidx.compose.ui.unit.Density
20
```
21

22
## Basic Usage
23

24
```kotlin
25
import androidx.compose.foundation.Image
26
import androidx.compose.material.Text
27
import androidx.compose.runtime.Composable
28
import androidx.compose.ui.text.font.Font
29
import androidx.compose.ui.text.font.FontFamily
30
import androidx.compose.ui.text.font.FontWeight
31
import org.jetbrains.compose.resources.*
32

33
@Composable
34
fun MyApp() {
35
    // Load string resources
36
    val title = stringResource(Res.string.app_title)
37
    val formattedMessage = stringResource(Res.string.welcome_message, "User")
38
    
39
    // Load image resources
40
    val icon = painterResource(Res.drawable.app_icon)
41
    val bitmap = imageResource(Res.drawable.profile_image)
42
    
43
    // Load font resources
44
    val customFont = Font(
45
        resource = Res.font.custom_font,
46
        weight = FontWeight.Bold
47
    )
48
    
49
    // Use resources in composables
50
    Text(text = title, fontFamily = FontFamily(customFont))
51
    Image(painter = icon, contentDescription = "App Icon")
52
}
53

54
// Non-composable usage
55
suspend fun loadResources() {
56
    val message = getString(Res.string.app_title)
57
    val imageBytes = getDrawableResourceBytes(
58
        getSystemResourceEnvironment(),
59
        Res.drawable.app_icon
60
    )
61
}
62
```
63

64
## Architecture
65

66
The library is built around several key concepts:
67

68
- **Resource Types**: Strongly-typed resource classes (StringResource, DrawableResource, FontResource, etc.)
69
- **Environment-Aware Loading**: Automatic selection based on locale, theme, and screen density
70
- **Cross-Platform Abstraction**: Single API with platform-specific implementations
71
- **Async Loading**: Non-blocking resource loading with intelligent caching
72
- **Compose Integration**: Deep integration with Compose runtime and state management
73

74
## Capabilities
75

76
### String Resources
77

78
Provides type-safe string loading with formatting support and localization.
79

80
```kotlin { .api }
81
@Composable
82
fun stringResource(resource: StringResource): String
83

84
@Composable  
85
fun stringResource(resource: StringResource, vararg formatArgs: Any): String
86

87
suspend fun getString(resource: StringResource): String
88
suspend fun getString(resource: StringResource, vararg formatArgs: Any): String
89
suspend fun getString(environment: ResourceEnvironment, resource: StringResource): String
90
```
91

92
[String Resources](./string-resources.md)
93

94
### Image and Drawable Resources
95

96
Handles images, vector graphics, and SVG files with density-aware loading and automatic format detection.
97

98
```kotlin { .api }
99
@Composable
100
fun painterResource(resource: DrawableResource): Painter
101

102
@Composable
103
fun imageResource(resource: DrawableResource): ImageBitmap
104

105
@Composable
106
fun vectorResource(resource: DrawableResource): ImageVector
107

108
suspend fun getDrawableResourceBytes(environment: ResourceEnvironment, resource: DrawableResource): ByteArray
109
```
110

111
[Image and Drawable Resources](./image-drawable-resources.md)
112

113
### Image Decoder Extensions
114

115
Extension functions for decoding raw image bytes into Compose graphics objects.
116

117
```kotlin { .api }
118
/**
119
 * Decodes a byte array of a Bitmap to an ImageBitmap. Supports JPEG, PNG, BMP, WEBP
120
 * Different platforms can support additional formats.
121
 */
122
fun ByteArray.decodeToImageBitmap(): ImageBitmap
123

124
/**
125
 * Decodes a byte array of a vector XML file to an ImageVector.
126
 * @param density density to apply during converting the source units to the ImageVector units.
127
 */
128
fun ByteArray.decodeToImageVector(density: Density): ImageVector
129
```
130

131
### Font Resources
132

133
Provides font loading with support for variable fonts, weights, and styles.
134

135
```kotlin { .api }
136
@Composable
137
expect fun Font(
138
    resource: FontResource,
139
    weight: FontWeight = FontWeight.Normal,
140
    style: FontStyle = FontStyle.Normal,
141
    variationSettings: FontVariation.Settings = FontVariation.Settings(weight, style)
142
): Font
143

144
suspend fun getFontResourceBytes(environment: ResourceEnvironment, resource: FontResource): ByteArray
145
```
146

147
[Font Resources](./font-resources.md)
148

149
### Plural String Resources
150

151
Handles quantity-based pluralized strings following CLDR plural rules.
152

153
```kotlin { .api }
154
@Composable
155
fun pluralStringResource(resource: PluralStringResource, quantity: Int): String
156

157
@Composable
158
fun pluralStringResource(resource: PluralStringResource, quantity: Int, vararg formatArgs: Any): String
159

160
suspend fun getPluralString(resource: PluralStringResource, quantity: Int): String
161
suspend fun getPluralString(resource: PluralStringResource, quantity: Int, vararg formatArgs: Any): String
162
```
163

164
[Plural String Resources](./plural-string-resources.md)
165

166
### String Array Resources
167

168
Provides access to arrays of localized strings.
169

170
```kotlin { .api }
171
@Composable
172
fun stringArrayResource(resource: StringArrayResource): List<String>
173

174
suspend fun getStringArray(resource: StringArrayResource): List<String>
175
suspend fun getStringArray(environment: ResourceEnvironment, resource: StringArrayResource): List<String>
176
```
177

178
[String Array Resources](./string-array-resources.md)
179

180
### Resource Environment and Context
181

182
Manages the environment context for resource selection including locale, theme, and density.
183

184
```kotlin { .api }
185
@Composable
186
fun rememberResourceEnvironment(): ResourceEnvironment
187

188
fun getSystemResourceEnvironment(): ResourceEnvironment
189
```
190

191
[Resource Environment](./resource-environment.md)
192

193
## Core Types
194

195
```kotlin { .api }
196
sealed class Resource(
197
    internal val id: String,
198
    internal val items: Set<ResourceItem>
199
)
200

201
data class ResourceItem(
202
    internal val qualifiers: Set<Qualifier>,
203
    internal val path: String,
204
    internal val offset: Long,
205
    internal val size: Long
206
)
207

208
class StringResource(id: String, val key: String, items: Set<ResourceItem>) : Resource(id, items)
209

210
class DrawableResource(id: String, items: Set<ResourceItem>) : Resource(id, items)
211

212
class FontResource(id: String, items: Set<ResourceItem>) : Resource(id, items)
213

214
class PluralStringResource(id: String, val key: String, items: Set<ResourceItem>) : Resource(id, items)
215

216
class StringArrayResource(id: String, val key: String, items: Set<ResourceItem>) : Resource(id, items)
217

218
class ResourceEnvironment(
219
    internal val language: LanguageQualifier,
220
    internal val region: RegionQualifier,
221
    internal val theme: ThemeQualifier,
222
    internal val density: DensityQualifier
223
)
224
```
225

226
## Qualifiers
227

228
```kotlin { .api }
229
interface Qualifier
230

231
class LanguageQualifier(val language: String) : Qualifier
232

233
class RegionQualifier(val region: String) : Qualifier
234

235
enum class ThemeQualifier : Qualifier {
236
    LIGHT, DARK;
237
    companion object {
238
        fun selectByValue(isDark: Boolean): ThemeQualifier
239
    }
240
}
241

242
enum class DensityQualifier(val dpi: Int) : Qualifier {
243
    LDPI(120), MDPI(160), HDPI(240), XHDPI(320), XXHDPI(480), XXXHDPI(640);
244
    companion object {
245
        fun selectByValue(dpi: Int): DensityQualifier
246
        fun selectByDensity(density: Float): DensityQualifier
247
    }
248
}
249
```
250

251
## Annotations
252

253
```kotlin { .api }
254
@RequiresOptIn("This API is experimental and is likely to change in the future.")
255
annotation class ExperimentalResourceApi
256

257
@RequiresOptIn("This is internal API of the Compose gradle plugin.")
258
annotation class InternalResourceApi
259
```
260

261
## Exceptions
262

263
```kotlin { .api }
264
class MissingResourceException(path: String) : Exception("Missing resource with path: $path")
265

266
class MalformedXMLException(message: String?) : Exception(message)
267
```