Using multiplatform resources in your app

Images

You can access drawable resources as simple images, rasterized images or XML vectors. SVG images are supported on all platforms except Android.

• To access drawable resources as Painter images, use the painterResource() function:

  @Composable
  fun painterResource(resource: DrawableResource): Painter {...}

  The painterResource() function takes a resource path and returns a Painter value. The function works synchronously on all targets except for web. For the web target, it returns an empty Painter for the first recomposition that is replaced with the loaded image in subsequent recompositions.

  • painterResource() loads either a BitmapPainter for rasterized image formats, such as .png, .jpg, .bmp, .webp, or a VectorPainter for the Android XML vector drawable format.

  • XML vector drawables have the same format as Android, except that they don't support external references to Android resources.

• To access drawable resources as an ImageBitmap rasterized image, use the imageResource() function:

  @Composable
  fun imageResource(resource: DrawableResource): ImageBitmap {...}

• To access drawable resources as an ImageVector XML vector, use the vectorResource() function:

  @Composable
  fun vectorResource(resource: DrawableResource): ImageVector {...}

Here's an example of how you can access images in your Compose Multiplatform code:

Image(
    painter = painterResource(Res.drawable.my_icon),
    contentDescription = null
)

Strings

Store all string resources in XML files in composeResources/values directories. A static accessor is generated for each item in each file.

<resources>
    <string name="app_name">My awesome app</string>
    <string name="title">Some title</string>
</resources>

@Composable
fun stringResource(resource: StringResource): String {...}

@Composable
fun stringResource(resource: StringResource, vararg formatArgs: Any): String {...}

Text(stringResource(Res.string.app_name))

suspend fun getString(resource: StringResource): String

suspend fun getString(resource: StringResource, vararg formatArgs: Any): String

coroutineScope.launch {
    val appName = getString(Res.string.app_name)
}

<resources>
    <string name="str_template">Hello, %2$s! You have %1$d new messages.</string>
</resources>

Text(stringResource(Res.string.str_template, 100, "User_name"))

Text(stringResource(Res.string.str_template, "User_name", 100.1f))

<resources>
    <string name="app_name">My awesome app</string>
    <string name="title">Some title</string>
    <string-array name="str_arr">
        <item>item \u2605</item>
        <item>item \u2318</item>
        <item>item \u00BD</item>
    </string-array>
</resources>

@Composable
fun stringArrayResource(resource: StringArrayResource): List<String> {...}

Text(stringArrayResource(Res.array.str_arr)[0])

suspend fun getStringArray(resource: StringArrayResource): List<String>

coroutineScope.launch {
    val appName = getStringArray(Res.array.str_arr)
}

<resources>
    <string name="app_name">My awesome app</string>
    <string name="title">Some title</string>
    <plurals name="new_message">
        <item quantity="one">%1$d new message</item>
        <item quantity="other">%1$d new messages</item>
    </plurals>
</resources>

@Composable
fun pluralStringResource(resource: PluralStringResource, quantity: Int): String {...}

@Composable
fun pluralStringResource(resource: PluralStringResource, quantity: Int, vararg formatArgs: Any): String {...}

Text(pluralStringResource(Res.plurals.new_message, 1, 1))

suspend fun getPluralString(resource: PluralStringResource, quantity: Int): String

suspend fun getPluralString(resource: PluralStringResource, quantity: Int, vararg formatArgs: Any): String

coroutineScope.launch {
    val appName = getPluralString(Res.plurals.new_message, 1, 1)
}

Fonts

Store custom fonts in the composeResources/font directory as *.ttf or *.otf files.

To load a font as a Font type, use the Font() function:

@Composable
fun Font(
    resource: FontResource,
    weight: FontWeight = FontWeight.Normal,
    style: FontStyle = FontStyle.Normal
): Font

For example:

val fontAwesome = FontFamily(Font(Res.font.font_awesome))

Raw files

To load any raw file as a byte array, use the Res.readBytes(path) function:

suspend fun readBytes(path: String): ByteArray

You can place raw files in the composeResources/files directory and create any hierarchy inside it.

For example, to access raw files, use the following code:

var bytes by remember {
    mutableStateOf(ByteArray(0))
}
LaunchedEffect(Unit) {
    bytes = Res.readBytes("files/myDir/someFile.bin")
}
Text(bytes.decodeToString())

coroutineScope.launch {
    val bytes = Res.readBytes("files/myDir/someFile.bin")
}

// bytes = Res.readBytes("files/example.png")
Image(bytes.decodeToImageBitmap(), null)

// bytes = Res.readBytes("files/example.xml")
Image(bytes.decodeToImageVector(LocalDensity.current), null)

// bytes = Res.readBytes("files/example.svg")
Image(bytes.decodeToSvgPainter(LocalDensity.current), null)

Generated maps for resources and string IDs

For ease of access, Compose Multiplatform also maps resources with string IDs. You can access them by using the filename as the key:

val Res.allDrawableResources: Map<String, DrawableResource>
val Res.allStringResources: Map<String, StringResource>
val Res.allStringArrayResources: Map<String, StringArrayResource>
val Res.allPluralStringResources: Map<String, PluralStringResource>
val Res.allFontResources: Map<String, FontResource>

An example of passing a mapped resource to a composable:

Image(painterResource(Res.allDrawableResources["compose_multiplatform"]!!), null)

Compose Multiplatform resources as Android assets

Starting with Compose Multiplatform 1.7.3, all multiplatform resources are packed into Android assets. This enables Android Studio to generate previews for Compose Multiplatform composables in Android source sets.

warning

Android Studio previews are available only for composables in an Android source set. They also require one of the latest versions of AGP: 8.5.2, 8.6.0-rc01, or 8.7.0-alpha04.

Using Multiplatform resources as Android assets also makes possible direct access from WebViews and media player components on Android, since resources can be reached by a simple path, for example Res.getUri("files/index.html").

An example of an Android composable displaying a resource HTML page with a link to a resource image:

AndroidView(factory = { WebView(it).apply
 {...}

The example works with this simple HTML file:

<title>Cat Resource</title>
 {...}

Both resource files in this example are located in the commonMain source set:

Accessing multiplatform resources from external libraries

If you want to process multiplatform resources using other libraries included in your project, you can pass platform-specific file paths to these other APIs. To get a platform-specific path, call the Res.getUri() function with the project path to the resource:

val uri = Res.getUri("files/my_video.mp4")

Now that the uri variable contains the absolute path to the file, any external library can use that path to access the file in a manner that suits it.

For Android-specific uses, multiplatform resources are also packed as Android assets.

Remote files

In the context of the resource library, only files that are part of the application are considered resources.

You can load remote files from the internet using their URL using specialized libraries:

• Compose ImageLoader

• Kamel

• Ktor client

Using Java resources

While you can use Java resources with Compose Multiplatform, they don't benefit from extended features provided by the framework: generated accessors, multimodule support, localization, and so on. Consider transitioning fully to the multiplatform resource library to unlock that potential.

With Compose Multiplatform 1.7.3, the resources API available in the compose.ui package is deprecated. If you still need to work with Java resources, copy the following implementation to your project to ensure that your code works after you upgrade to Compose Multiplatform 1.7.0 or above:

internal fun painterResource(resourcePath: String): Painter
 {...}