Skip to content
CONTACT SALESSTART BUILDING

Map components

for developers

enterprise plans

deprecated

Builder.io is transitioning from manual component mapping to Component indexing, which automatically discovers and maps your design system components.

To migrate away from component mapping, visit the Component mapping migration guide.

Whether you Generate Code with Visual Editor or Generate Code with Builder CLI, component mapping provides a way to customize the code output to use your own code as part of the code generation.

What to know

  • Connect Figma components to code components, so that when you use your Figma components your code components are used during code generation.
  • To map components, you must export your design from Figma with Precise Mode.
  • You must also publish .mapper files to successful map components.

Builder generates code from your Figma design that doesn't depend on specific libraries or component methods.

If you want to use existing components in your codebase instead of generating new ones, you can use component mapping.

Image of a product card and a code snippet that correspond to one another.

The following terms are useful to understand in relation to this process:

  • Figma component: reusable design elements that can be accessed across design spaces. For more details, see Figma's Guide to components in Figma.
  • Code component: reusable code elements that can be accessed from across your codebase. Depending on your application's framework, the exact code may look different but the concept is the same.
  • Mapping: Builder connects Figma components to code components, so that when code is generated from a Figma design the existing code components are used wherever possible.
  • .mapper file: This file lives in your codebase and aids Builder in connecting your Figma components to your code components. It also provides customization for using your component.

Mapping a component is a three-stage process:

  1. Create a .mapper file that connects a code component to a Figma component.
  2. Publish a mapped component to your Builder Space.
  3. Generate code with your mapped components.

To create a .mapper file:

  1. Open a terminal window with its current location set to your project's directory.
  2. Create a Figma component that represents a code component already within your codebase.
  3. Click the Figma component and then open the Figma Builder plugin.
  4. Go to the Design System tab and click Map new components.
  5. A script is presented with the generate command. Copy this script to your terminal window.
  6. Run the command. When prompted, choose your code component from the list provided by the command line. This creates a new .mapper file.

Below is an example of a .mapper file.

The code below shows a code component, Button, being mapped to a Figma component through a unique ID.

Figma component variables, such as Variant and Size in this example, can be accessed via the figma object from within the mapper() method.

import { figmaMapping } from "@builder.io/dev-tools/figma";
import { Button } from "@/components/ui/button";

figmaMapping({
  componentKey: "9ca66d3a1f5b2c4e7d8a0b9f",
  mapper(figma) {
    return (
      <Button
        variant={figma.Variant?.toLowerCase()}
        size={figma.Size?.toLowerCase()}
        disabled={figma.State === "Disabled"}
      >
        {figma.$textContent || figma.Text || "Button"}
      </Button>
    );
  },
});

Important: Your import paths within .mapper files will be reproduced verbatim during code generation. Use published package names or TypeScript path aliases (configured in tsconfig.json) within your .mapper files to ensure your generated code is not broken.

You must publish your mapped components for Builder to know about them. Once your components are published, they are available for use during code generation.

To publish mapped components:

  1. Confirm your local project has .mapper files for the code components you wish to map.
  2. Run the following command in your application's directory:
npx "@builder.io/dev-tools@latest" figma publish
  1. Builder CLI identifies all mapped components (that is, .mapper files) within your application.
  2. When prompted, choose Publish. This publishes the mappings to Builder.

Now, when you use code generation, Figma components mapped to code components are used whenever possible.

Once your components have been mapped and published:

  1. Within Figma, choose a design that makes use of your mapped Figma component.
  2. When exporting your design with the Builder Figma plugin, choose Precise Mode. For more details on Precise Mode, see Figma export modes and Set up for precise mode.
  3. Click Export Design.
  4. Choose your method of code generation. For more details, see Generate Code with Visual Editor or Generate Code with Builder CLI.

Builder's code generation uses your mapped components within its results, reducing code complexity and duplication.

In the video below, code is generated with the Builder CLI. A published mapped component is present in the design and can be seen in the generated code.

To see more specific details about mapping components, see specialized documentation for working with TypeScript, Angular, and React.

Was this article helpful?