Mapping with variants

If a simple one-to-one mapping is not sufficient, you can create more advanced mappings, using Figma variants and writing a wrapper composable function to process the information from Figma.

We will use this chip component that has three variants — Configuration: success, warning, and error. In code, these variants correspond to composable functions SuccessChip, WarningChip, and ErrorChip respectively.

Download the sample project

We will use the HelloMapping project downloaded in the previous section. Please follow the instructions on the Mapped Components Tutorial page if you haven’t already downloaded it.

Existing components in code

Let’s take a look at the code for these chips.

Open com/example/hellomapping/ui/Chip.kt and find the definitions for SuccessChip, WarningChip, and ErrorChip.

The signatures of these composable functions are shown below. They have the same parameters, but they render different designs:

@Composable
fun SuccessChip (
    text: String,
    modifier: Modifier = Modifier
) { … }

@Composable
fun WarningChip (
    text: String,
    modifier: Modifier = Modifier
) { … }

@Composable
fun ErrorChip (
    text: String,
    modifier: Modifier = Modifier
) { … }

Copy Figma example

We’ll be using an existing Figma file as an example for this tutorial. Make sure you’re logged into your Figma account.

1. Download Mapping-With-Variants.fig to your computer.

2. In Figma, go to the file browser. Along the left-hand side, hover over Drafts. A + icon will appear — click it, then Import to import the Mapping-With-Variants.fig file that you just downloaded.

   

Create UI Packages in Figma

This file has the Chip component already set up with variants, and a layout of a card that we want to add the chip to. We'll be adding a parameter to pass the text content.

1. With the Relay for Figma plugin open, select the Chip component and click Create UI Package.

   

2. With the Chip component still selected, add a description to the summary box, for example, “Chip component to display status, mapped to SuccessChip, WarningChip and ErrorChip”.

3. Select the text layer in one of the chip variants (⌘ + click on Mac, or Ctrl + click on Windows or Linux on the text). In the Relay for Figma plugin, click + next to Parameters to add a text-content parameter. Rename it to text.

   

Placing mapped component in a card

Let’s use this chip in a card.

1. Select the StatusCard component and click Create UI Package.

   

2. Copy and place the Warning variant of Chip in the card under the Chip-Container layer.

3. Select the text layer inside the instance of the button (⌘ + click on Mac, or Ctrl + click on Windows or Linux), edit the text content to override it with Be Careful.

   

Using a wrapper function

In this example, we have one Figma component that we would like to map to three separate composables (in this instance, SuccessChip, WarningChip, and ErrorChip), depending on the variant. Since a mapping file can only map one Figma component to one composable function, we need to create a wrapper function that takes the parameters passed from Figma and calls one of the three composables, depending on the variant.

For your convenience, we have included an example of such a wrapper function, MyChip, in the HelloMapping Android Studio project.

1. Go to the Android studio and open com/example/hellomapping/MyChip.kt.

   

   The MyChip function looks like this. The parameter design is derived from Chip’s selected variant. You can use this information and other parameters to do any advanced transformation in code.

   @Composable
   fun MyChip(
       modifier: Modifier = Modifier,
       design: String = "Configuration=Success",  // See note below
       text: String
   ) {
       when (design) {
           "Configuration=Success" -> SuccessChip(modifier = modifier, text = text)
           "Configuration=Warning" -> WarningChip(modifier = modifier, text = text)
           "Configuration=Error" -> ErrorChip(modifier = modifier, text = text)
       }
   }
   

Writing a mapping file

Create a mapping file to map the packaged component in Figma to the wrapper function you just created.

1. Go to your HelloMapping Android Studio project, and select the Project view.

   

2. Under ui-package-resources/mappings/ (created in the 1-to-1 mapping tutorial), create a file called chip.map.

   

3. Copy and paste the following code, then save and close the file. This file tells the code generator how to reach the desired composable function, in this case, com.example.hellomapping.MyChip.

   {
       "target": "MyChip",
       "package": "com.example.hellomapping"
   }
   

Import design from Figma

Now, let's see this component in the code!

1. Add a new named version of your Figma file. In the Figma plugin, select your component and click Share with developer. Under **Share version history, enter a title and description of your new version, and click Save.
2. In the upper right-hand corner of Figma, click on the Share button. In the dialog box that opens, click Copy link.
3. Switch to the Android Studio project. Go to File > New > Import UI Packages… from the Android Studio menu bar.
4. Paste the URL of your Figma file and click Next. If you see a keychain prompt, enter your password and click Always Allow.
5. Wait for the file to be downloaded. On success, you should see the preview of two components: chip and status_card. Click Finish.
6. Click in the main toolbar to build your project. This may take a couple of minutes. Click on the Build tab at the bottom of Android Studio to view build results.

Inspecting the generated code

Generated code has now been added to your project.

1. Using Android view, open app/java/com/example/hellomapping/statuscard/StatusCard.kt, which is the generated Jetpack Compose code for the StatusCard Figma component.

   

2. You’ll see a preview of the imported card.

   

   This is the generated Jetpack Compose code for our Figma component. In the code, you can see that MyChip is used in the place of the chip, with the parameters based on the text content and selected variant in the Figma file (again, noting that in a future version of Relay, the design parameter will be something more type safe than a string).

   @Composable
   fun ChipInstance(modifier: Modifier = Modifier) {
       MyChip(
           design = "Configuration=Warning",
           text = "Be Careful",
           modifier = modifier
       )
   }