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.
Mapping functions, which help you map your Figma components to your code components, are essential for leveraging your existing code components to generate code when using the Builder Figma plugin.
- Mapped components should always be in a
.mapperfile. For more details on how to generate mapped components through the Builder CLI, visit Map components. - Component mapping functions provide the
figmaobject. This object has access to your Figma component's properties and content. - Optionally create a generic mapper that is applied to all Figma elements.
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.
For an overview of component mapping, visit Map components. Below is an example of a mapped component:
// mappings/SimpleButton.mapper.tsx
import { figmaMapping, type BaseFigmaProps } from "@builder.io/dev-tools/figma";
import SimpleButton from "@/components/SimpleButton";
interface FigmaSimpleButtonProps extends BaseFigmaProps {
ButtonText: string;
Variant?: "Default" | "Default-Hover" | "Dark-Hover" | "Dark";
}
figmaMapping({
componentKey: "component-id",
mapper(figma: FigmaSimpleButtonProps) {
return (
<SimpleButton
text={figma.ButtonText}
variant={figma.Variant?.toLowerCase() ?? "default"}
/>
);
},
});
In the code example above:
- The mapping function is the
mapper()method within the object passed to thefigmaMapping()function - This function has access to an object,
figma, which contains details about the Figma component, identified by the"component-id". - The Figma component's properties, such as
ButtonTextandVariant, are used as prop values within theSimpleButtoncomponent.
The diagram below shows how the Figma properties, on the left, correspond to the mapper() method, on the right:
This next screenshot shows how Figma layers, on the left, correspond to code, on the right.
This way, the Builder Figma Plugin converts your Figma designs directly into React code, simplifying the process of transforming your design ideas into real, functional code components.
The figma object, provided by the mapper() method, has several properties and functions attached to it, which can be used to build more robust
Properties on your Figma component can be accessed with the same name on the figma object. For example, if your Figma component has an OnSale boolean property, access the value of this property with the mapper() method with figma.OnSale.
In the example below, multiple Figma properties, including Version, ProductName, Price, and OnSale, are passed to the ProductCard component.
// mappings/ProductCard.mapper.tsx
import { figmaMapping, type BaseFigmaProps } from "@builder.io/dev-tools/figma";
import { ProductCard } from "@/components/ProductCard";
interface FigmaProductCardProps extends BaseFigmaProps {
OnSale?: boolean;
ProductName?: string;
Price?: string;
Version?: "Default";
}
export default figmaMapping({
componentKey: "component-id",
mapper(figma: FigmaProductCardProps) {
return (
<ProductCard
version={figma.Version?.toLowerCase() ?? "default"}
product={{
name: figma.ProductName ?? "",
price: figma.Price ?? "",
isOnSale: figma.OnSale ?? false,
}}
/>
);
},
});Although Builder's Figma plugin uses AI semantic matching to automatically identify which components in your codebase correspond to your components in Figma, every design is unique and might require additional attention during the mapping process.
The video below shows opening the plugin in Figma and editing the mapping function for an example design.
In addition to the properties you define on the component, the figma object provides access to other helpful properties.
Purpose: Retrieves all direct child nodes of the current Figma design and returns an array.
Example: Below is an example of using $children for a button.
export default figmaMapping({
componentKey: "component-id",
mapper(figma: FigmaProductListingProps) {
return (
<Button>
{figma.$children}
</Button>
)
}
});Options: exclude, an array of strings specifying the names of child nodes to exclude from the result.
Note that $children is zero-indexed.
Purpose: Retrieves the text content from the current Figma design node. If the node is a text node, it returns its characters. It aggregates the text from all child text nodes for group, frame, component, or instance nodes and returns it as a single string.
Example: Below is an example of using $textContent to extract text from a Figma node whose children are startIcon, text and endIcon.
export default figmaMapping({
componentKey: "component-id",
mapper(figma: FigmaProductListingProps) {
return (
<Button>
{figma.$children[1].$textContent}
</Button>
)
}
});The figma object also provides helper methods which can be used to find and manipulate elements within the Figma component.
Purpose: Maps a specific child node of the current Figma component by its layer name.
Parameters: name, a string that indicates the name of the child node to map.
Example: The code snippet below retrieves a child element in Figma by its name dialog for display within the <div>.
export default figmaMapping({
componentKey: "component-id",
mapper(figma: FigmaProductListingProps) {
return (
<div>
{figma.$findOneByName('dialog')}
</div>
)
}
});Purpose: finds the first node that meets specified criteria.
Parameters: takes a callback function
Example: The example below specifies a node with the name of Heading.
export default figmaMapping({
componentKey: "component-id",
mapper(figma: FigmaProductListingProps) {
return (
<div>
{figma.$findOne((node) => {
return node.name === "Heading"
})}
</div>
)
}
});