Using multiplatform resources in your app
When you've set up the resources for your project, build the project to generate the special Res
class which provides access to resources. To manually generate the Res
class and all the resource accessors, build or re-import the project in the IDE.
After that, you can use the generated class to access the configured multiplatform resources from your code or from external libraries.
Customizing accessor class generation
You can customize the generated Res
class to suit your needs using Gradle settings.
In the compose.resources {}
block of the build.gradle.kts
file, you can specify several settings that affect the way the Res
class is generated for your project. An example configuration looks like this:
publicResClass
set totrue
makes the generatedRes
class public. By default, the generated class is internal.packageOfResClass
allows you to assign the generatedRes
class to a particular package (to access within the code, as well as for isolation in a final artifact). By default, Compose Multiplatform assigns the{group name}.{module name}.generated.resources
package to the class.generateResClass
set toalways
makes the project unconditionally generate theRes
class. This may be useful when the resource library is only available transitively. By default, Compose Multiplatform uses theauto
value to generate theRes
class only if the current project has an explicitimplementation
orapi
dependency on the resource library.
Resource usage
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 thepainterResource()
function:@Composable fun painterResource(resource: DrawableResource): Painter {...}The
painterResource()
function takes a resource path and returns aPainter
value. The function works synchronously on all targets except for web. For the web target, it returns an emptyPainter
for the first recomposition that is replaced with the loaded image in subsequent recompositions.painterResource()
loads either aBitmapPainter
for rasterized image formats, such as.png
,.jpg
,.bmp
,.webp
, or aVectorPainter
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 theimageResource()
function:@Composable fun imageResource(resource: DrawableResource): ImageBitmap {...}To access drawable resources as an
ImageVector
XML vector, use thevectorResource()
function:@Composable fun vectorResource(resource: DrawableResource): ImageVector {...}
Here's an example of how you can access images in your Compose Multiplatform code:
Strings
Store all string resources in XML files in composeResources/values
directories. A static accessor is generated for each item in each file.
Simple strings
To store a simple string, add a <string>
element to your XML:
To get string resources as a String
, use the following code:
For example:
For example:
You can use special symbols in string resources:
\n
— for a new line\t
— for a tab symbol\uXXXX
— for a specific Unicode character
String templates
Currently, arguments have basic support in string resources:
There is no difference between %...s
and %...d
when using string templates with arguments from composable code, for example:
String arrays
You can group related strings into an array and automatically access them as a List<String>
object:
To get the corresponding list, use the following code:
For example:
For example:
Plurals
When your UI displays quantities of something, you might want to support grammatical agreement for different numbers of the same thing (one book, many books, and so on) without creating programmatically unrelated strings.
The concept and base implementation in Compose Multiplatform are the same as for quantity strings on Android. See the Android documentation for more about best practices and nuances of using plurals in your project.
The supported variants are
zero
,one
,two
,few
,many
, andother
. Note that not all variants are even considered for every language: for example,zero
is ignored for English because it is the same as any other plural except 1. Rely on a language specialist to know what distinctions the language actually insists upon.It's often possible to avoid quantity strings by using quantity-neutral formulations such as "Books: 1". If this doesn't worsen the user experience,
To define a plural, add a <plurals>
element to any .xml
file in your composeResources/values
directory. A plurals
collection is a simple resource referenced using the name attribute (not the name of the XML file). As such, you can combine plurals
resources with other simple resources in one XML file under one <resources>
element:
To access a plural as a String
, use the following code:
For example:
For example:
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:
For example:
Raw files
To load any raw file as a byte array, use the Res.readBytes(path)
function:
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:
Convert byte arrays into images
If the file you are reading is a bitmap (JPEG, PNG, BMP, WEBP) or an XML vector image, you can use the following functions to convert them into ImageBitmap
or ImageVector
objects suitable for the Image()
composable.
Access the raw files as shown in the Raw files section, then pass the result to a composable:
On every platform except Android, you can also turn an SVG file into a Painter
object:
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:
An example of passing a mapped resource to a composable:
Compose Multiplatform resources as Android assets
Starting with Compose Multiplatform 1.7.0-rc01, all multiplatform resources are packed into Android assets. This enables Android Studio to generate previews for Compose Multiplatform composables in Android source sets.
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:
The example works with this simple HTML file:
Both resource files in this example are located in the commonMain
source set:
Interaction with other libraries and resources
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:
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:
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.0-rc01, 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:
What's next?
Check out the official demo project that shows how resources can be handled in a Compose Multiplatform project targeting iOS, Android, and desktop.