Custom Components Manual Prop Mapping

Want more control over how Locofy maps the props of your custom components when importing your component library? We’ll show you how to do this using the Locofy CLI.

Code component

import { FunctionComponent } from "react";
import styles from "./Card.module.css";
 
export type CardProp = {
  badge: string;
  item: {
    name: string;
    image: string;
    rating: number;
    locations: {
      name: string;
    }[];
  };
};

In this example, I have already written the code for my component and defined all the properties.

Figma component

In my Figma component, I have created the layers for the various properties.

Mapping via UI in Plugin

After pushing your components, you can click on the folder icon next to the project name.

Next, click on pencil icon and click "Props mapping".

You can now map your code components values to Figma component values.

Once all properties are mapped, you will see a green tick between custom component prop and Figma component property. You do not need to map all the props. For example, you can leave out the optional props.

Note: Array props are fully supported right now as Figma does not have a equivalent array property.

Mapping via your locofy.config.json file

You need to define which code component prop should be mapped to which Figma component layer. You will be using the Figma component layer name, not the Figma component property name.

Here’s how the code should look like based on the examples above:

{
  "components": ["./src/components/Card.tsx"],
  "componentsMapping": [
    {
      "path": "./src/components/Card.tsx",
      "figmaComponent": "Card",
      "props": {
        "badge": "Superhost",
        "item": {
          "name": "listing title",
          "rating": "rating",
          "locations": [
            {
              "name": "listing subtitle"
            }
          ]
        }
      }
    }
  ],
  "projectId": "2mYKttmuPiV11gUqXAU7Krha1Pn",
  "layerMapping": [],
  "projectName": "Website project"
}

Using the Locofy MCP to Auto-Generate Config

Locofy MCP can also generate the config file for you. Make sure to set it up properly by following this guide (opens in a new tab) and then follow the steps:

Open your project in your IDE and enter Agent mode.
In Cursor, press Command + I.

In the Agent chat, reference the component files you want MCP to scan using @ mentions. You can include multiple files or globs. For example:

@src/components/Card.tsx @src/components/Badge.tsx generate config schema for all components in the given files

You can also use patterns like:

@src/components/**/*.tsx generate config schema for all components in the given files

The IDE will invoke the Locofy MCP tool for config generation. You’ll see a tool call confirmation in the panel. MCP analyzes the referenced files, detects components and their props, and writes the output to a locofy.config.json file at your project root.

Open locofy.config.json and review the generated entries. Example code:

{
  "components": ["./src/components/Badge.tsx"],
  "componentsMapping": [
  {
   "path": "./src/components/Badge.tsx",
   "figmaComponent": "Badge",
   "props": {
    "color": "Color"
  } 
 }
],
"props": [
{
  "name": "color",
  "type": "enum",
  "enum": ["sky", "purple", "green"],
  "defaultValue": "sky",
  "previewValue": "green",
  "valueMapping": {
    "sky": ["Sky"],
    "purple": ["Purple"],
    "green": ["Green", "Severity - Low"]
      }
    }
  ]
}

Save and commit the file. If you previously mapped props via the plugin UI, remove those mappings and Sync again to avoid conflicts.

Previously imported your component library?

If you have previously imported your component library, please remember to remove all your existing mapping by clicking the pencil icon and “remove mapping”. Then click on “Sync again”.

Wrapper Component Error Handling