Mapping with variants

Stay organized with collections Save and categorize content based on your preferences.

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.

Mapping with variants overview diagram

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.

Chip.kt in the Android view

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.

    Mapping-With-Variants.fig

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.

    Create UI Package button in the plugin
  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.

    The Figma plugin with the StatusCard selected

Placing mapped component in a card

Let’s use this chip in a card.

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

    The Figma plugin with the StatusCard selected
  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.

    Placing the instance of Chip to the StatusCard

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.

    MyChip.kt in the Android view

    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.

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

    chip.map in the project view
  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

Let’s now see this component in code!

  1. Add a new named version of your Figma file. Go to File > Save to Version History, and then enter a title and description of your new version (any title and description works here).
  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 Make Project button 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.

    StatusCard in the Android view
  2. You’ll see a preview of the imported card.

    Preview of the StatusCard

    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
        )
    }