With the Builder Figma plugin, you can map your Figma designs to your React components, enabling seamless integration between design and code.
Component mappings define how elements in your Figma designs (like buttons, cards, or navigation components) should be translated into corresponding code components in your application.
At its core, a mapping function:
- Takes Figma component properties as input
- Transforms these properties into props for your React component
- Returns JSX that represents how your component should be rendered
This allows you to maintain design consistency between your Figma designs and your actual application code, making the design-to-code workflow much more efficient.
To get the most out of this document, you should:
- Have a Next.js, Remix, React with Vite, or similar React app with components.
- Have a Enterprise Builder Space.
- Have design components in Figma.
- Make sure the Builder Figma plugin is accessing the same Space as your codebase.
Component mapping is the process that connects your Figma designs to their code representation. Here's a high-level overview of how it works:
- Create Mapper Files: Create
.mapper.tsxor.mapper.tsfiles in your repository that define how Figma components translate to code. - Publish Mappings: Use the CLI to publish your mappings to your Builder.io space, making them available to the Figma plugin.
- Generate Code: When you export from Figma, the plugin uses your mappings to generate code that matches your actual components.
Mapper files must be named .mapper.{ts,js,jsx,tsx}. These files live in your repo and use the figmaMapping() function to connect Figma components to code components. Here's a simple example for React.
import { figmaMapping } from "@builder.io/dev-tools/figma";
import { Button } from "@/components/ui/button";
figmaMapping({
// Identify your Figma component (using componentKey or URL)
componentKey: "button-component-key",
// Define how Figma properties map to your component
mapper(figma) {
return (
<Button
variant={figma.Variant?.toLowerCase()}
size={figma.Size?.toLowerCase()}
disabled={figma.State === "Disabled"}
>
{figma.$textContent || figma.Text || "Button"}
</Button>
);
},
});The goal is to have these .mapper.tsx/ts files in your repository, which define how your Figma components should be represented in code.
This files can be anywhere within the repo, and multiple figmaMapping() can be in the same file. You could even have all the mappings in a single .mapper.* file.
You can create mappings in two ways:
- Manually: Write mapper files directly, giving you precise control over the mapping logic.
- Using the CLI Generator: Use our AI-powered CLI tool to automatically generate mappings based on your Figma components and code components.
After creation, your component mappings live in your repository as regular .mapper.ts or .mapper.tsx files. This brings several important benefits:
- TypeScript Integration: Mapping files are typechecked just like any other file in your codebase, helping you catch errors early
- Version Control: Use git or other source control systems to track changes to your mappings
- Code Reviews: Mappings can be part of your normal code review process
- Continuous Maintenance: You can edit mapping files manually any time, just like other code files
Remember that figma generate is only for the initial creation of mappings. After that, you can maintain and improve them with your regular development workflow. When you make changes to your mappings, simply run the publish command again to deploy them:
npx builder.io figma publishThis workflow allows your team to treat component mappings as a first-class part of your codebase, ensuring they evolve alongside your components.