Component mapping functions

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.

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.

What to know

Mapped components should always be in a .mapper file. For more details on how to generate mapped components through the Builder CLI, visit Map components.
Component mapping functions provide the figma object. This object has access to your Figma component's properties and content.
Optionally create a generic mapper that is applied to all Figma elements.

About mapping functions

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.

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 the figmaMapping() 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 ButtonText and Variant, are used as prop values within the SimpleButton component.

The diagram below shows how the Figma properties, on the left, correspond to the mapper() method, on the right:

Image of properties in Figma circled and an arrow pointing from them to their corresponding code.

This next screenshot shows how Figma layers, on the left, correspond to code, on the right.

Image of layers in Figma circled and an arrow pointing from them to their corresponding code.

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

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,
        }}
      />
    );
  },
});

Editing mappings with the Builder plugin

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.

Additional properties

In addition to the properties you define on the component, the figma object provides access to other helpful properties.

`figma.$children`

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.

`figma.$textContent`

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

Additional methods

The figma object also provides helper methods which can be used to find and manipulate elements within the Figma component.

`figma.$findOneByName(name)`

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

`figma.$findOne(node)`

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

`figma.$visit(callback)`

Purpose: Traverses all child nodes of the current Figma design and applies a given function to each node.

Callback Parameters:

node: The current child node being visited.

Usage:

node.$textContent: Retrieves the text content of the child node.
node.name: Retrieves the layer name of the child node in Figma.
node.inputs: Retrieves the properties (inputs) set on the child node.
node.componentName: Retrieves the name of the Builder component that the child node maps to.

Example: The example below iterates over nodes and converts nodes named Header into <h1> HTML tags with their content, and directly returns the text content of nodes named Content.

export default figmaMapping({
  componentKey: "component-id",
  mapper(figma: FigmaProductListingProps) {
    return figma.$visit((node) => {
      if (node.name === "Header") {
        return <h1>{node.$textContent}</h1>;
      } else if (node.name === "Content") {
        return node.$textContent;
      }
    });
  }
});

If your components or prop types aren't showing up in the plugin, or the AI isn't mapping your props at all, be sure that you are exporting your components and specify types for the props. For more detail, read Mapping components from libraries.

Component mapping examples

The following examples provide multiple demonstrations of component mapping, from simple to more complex.

Basic button mapping

figmaMapping({
  componentKey: "button-component-key",
  mapper(figma) {
    return (
      <Button
        color={figma.Color?.toLowerCase()}
        size={figma.Size?.toLowerCase()}
        type={figma.Variant?.toLowerCase()}
      >
        {figma.$children}
      </Button>
    );
  },
});

Hero section with multiple content areas

figmaMapping({
  componentKey: "hero-component-key",
  mapper(figma) {
    const heading = figma.Heading;
    const supportingText = figma.$findOneByName("Supporting Text").$textContent;
    const navigation = figma.$findOneByName("Navigation");

    return (
      <Hero
        heading={heading}
        supportingText={supportingText}
        navigation={navigation}
      />
    );
  },
});

Get content from specific child layers

figmaMapping({
  componentKey: "button-component-key",
  mapper(figma) {
    // Use the text from the 2nd child ($children is zero indexed)
    const text = figma.$children[1].$textContent;

    return <Button>{text}</Button>;
  },
});

Another option is to retrieve children by their layer name:

figmaMapping({
  componentKey: "button-component-key",
  mapper(figma) {
    const text = figma.$findOneByName("Label").$textContent;

    return <Button>{text}</Button>;
  },
});

Use your own CSS classes

figmaMapping({
  componentKey: "button-component-key",
  mapper(figma) {
    // Make an array to hold the CSS class names
    const classes = ["button"];

    // If figma.variant is 'primary', add the 'button-primary' class
    if (figma.variant === "primary") {
      classes.push("button-primary");
    }

    // Return a button with className applied
    return <button className={classes.join(" ")}>{figma.Text}</button>;
  },
});

Advanced table example

figmaMapping({
  componentKey: "29938639a346fd304f89cbbdd9377064ac6426c1",
  mapper(figma) {
    // Extract columns data
    const columns =
      figma.$children?.map((column) => {
        const header = column.$findOneByName("Header")?.$textContent ?? "";
        return { name: header, uid: header.toLowerCase() };
      }) ?? [];

    // Extract rows data
    const firstColumn = figma.$children?.[0];
    const rowsFrame = firstColumn?.$findOneByName("Rows");
    const rowCount = rowsFrame?.$children?.length ?? 0;

    // Create rows data structure
    const rows = Array.from({ length: rowCount }, (_, rowIndex) => {
      const rowData = {};
      figma.$children?.forEach((column) => {
        const rowItem = column.$findOneByName("Rows")?.$children?.[rowIndex];
        const cellContent =
          rowItem?.$findOneByName("Row item")?.$textContent ?? "";
        const columnId =
          column.$findOneByName("Header")?.$textContent?.toLowerCase() ?? "";
        rowData[columnId] = cellContent;
      });
      return { id: rowIndex, ...rowData };
    });

    return (
      <TableView
        aria-label="Table"
        isQuiet={figma.Style === "Quiet"}
        selectionMode={
          figma["Selection Column"] === "True" ? "multiple" : "none"
        }
      >
        <TableHeader columns={columns}>
          {(column) => <Column>{column.name}</Column>}
        </TableHeader>
        <TableBody items={rows}>
          {(item) => <Row>{(columnKey) => <Cell>{item[columnKey]}</Cell>}</Row>}
        </TableBody>
      </TableView>
    );
  },
});

Unsupported JSX syntax

Component mapping supports a subset of JSX syntax. The design generation process handles unsupported syntax by either removing the unsupported elements or throwing validation errors.

Function expressions

Function expressions are one feature of JSX syntax that component mapping does not support. Don't assign function expressions to props in the JSX returned by the mapper() function. The code generation process implements the function logic automatically or requires manual implementation after generating the code.

Omit these props that commonly use function expressions:

Event handlers: onClick, onPress, onSubmit
Form handlers: onChange, onInput
Interaction handlers: onHover, onFocus

The following examples compare incorrect and correct approaches to function expressions in props:

// ❌ Functions included

// imports
figmaMapping({
  componentKey: "component-id",
  mapper(figma) {
    return (
      <MyComponent
        onPress={() => {}}
        label={figma.ButtonText}
      />
    );
  },
});

// ✅ Functions omitted

// imports
figmaMapping({
  componentKey: "component-id",
  mapper(figma) {
    return (
      <MyComponent
        label={figma.ButtonText}
      />
    );
  },
});

Generic mapping function

The generic mapping function automates mapping complex Figma designs, including grid-like structures. It is versatile enough to map any non-component Figma node to any corresponding code component or element.

Automating the mapping of grid-like structures is particularly useful for developers working with complex layouts that otherwise would require extensive effort to map.

How this works

Builder's generic mapping function runs on each non-component layer within your Figma design. These layers can be converted into any element or code component based on their properties.

This gives a high degree of flexibility to handle designs that include a mix of Figma components and non-component structural layers that should be treated more specifically than generic wrappers.

This function integrates with Builder's existing findOne() logic and enhances its capability to handle diverse and complex designs.

Generic mapping example

In the mappings/ folder, create a genericMapper.mapper.tsx. Below is an example where different Figma nodes are mapped based on their names.

Framework

Meta-Framework

SDK Generation

// mappings/genericMapper.mapper.tsx

import { figmaMapping, type BaseFigmaProps } from "@builder.io/dev-tools/figma";
import { Grid } from "@/components/Grid";

figmaMapping({
  genericMapper(figma: BaseFigmaProps) {
    if (figma.$name === "Grid row") {
      return <Grid>{figma.$children}</Grid>;
    } else if (figma.$name === "Section") {
      return <section>{figma.$children}</section>;
    }
    // For other nodes, do not apply the generic
    // mapper and keep the default rendering behavior
    return undefined;
  },
});

In this example:

A Figma node named Grid row is automatically wrapped in a <Grid> component.
A node named Section is mapped to a <section> HTML element.
Nodes that do not match specific criteria retain their default rendering behavior for flexibility and control over the design-to-code process.

Inspect generic mapping function

If you publish a generic mapper function, it displays in the Builder Figma Plugin. However, the plugin does not show a generic mapper function if you don't publish one.

To display a generic mapper function in the Builder Figma Plugin, click on the Generic Mapper section to expand the mapping function as in the screenshot below:

Image of the builder Figma plugin and a note with an arrow to the other nodes section. The note says, "In the plugin, Generic Mapper function is here".

What's next

For more details on the basics of mapping components, visit Map components. If you encounter issues exporting Figma components to code, visit Debug view.

Certain parts of this workflow use AI. For more information, visit How Builder Uses AI.