Visual Copilot: Mapping Functions

in beta

for developers

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.

Prerequisites

To get the most out of this document, you should:

Be familiar with Mapping Components with the Builder Figma Plugin.
Be running your app along with Devtools.
Check to make sure the Builder Figma plugin is accessing the same Space as your codebase (which is running Devtools) is integrated with.

A mapping function is like a translator. Imagine you speak English, and your friend speaks another language. You need a translator to understand each other. In this case, the mapping function is the translator between your design in Figma and your code in React.

How mapping functions work

A mapping function works by connecting your Figma design components to your React code components. For instance, consider a Button in your Figma design that has specific properties like Color, Size, and Variant, and a Button in your React code that has props like color, size, and type.

The mapping function understands the Figma properties and determines how to apply them to the Button component in your React code. So, if your Figma Button is primary, large, and contained, the mapping function helps create a React Button with the same color, size, and type. The diagram below shows how the Figma properties, on the left, correspond to code, 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, Visual Copilot converts your Figma designs directly into React code, simplifying the process of transforming your design ideas into real, functional code components.

Using mapping functions

To use mapping functions effectively, you should know where to access them in the plugin and how to edit them if needed. This section covers where to find them along with an in-depth example of mapping Figma properties to React props.

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.

Mapping Figma properties to React props

As in the above video, when you initiate a mapping within the Builder Figma Plugin, the plugin generates a default mapping function based on AI semantic matching.

This Mapper() function takes an object representing the Figma component's properties and returns a React component with the mapped properties. All TypeScript code such as toLowerCase() is valid within the function.

You have the liberty to modify and refine these auto-generated mapping functions, ensuring that the final code aligns with the design intent.

Helper properties and methods

When mapping, there are times when you might need a little extra help to get the Figma property matched up with the right React prop. That's where the figma parameter in the mapper function comes into play. It's an object that provides access to various properties and methods, which are handy for dealing with more complex mapping tasks.

`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.

function Mapper(figma: FigmaButtonProps) {
  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. For group, frame, component, or instance nodes, it aggregates the text from all child text 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.

function Mapper(figma: FigmaButtonProps) {
  return (
    <Button>
      {figma.$children[1].$textContent}
    </Button>
  )
}

`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>.

function Mapper(figma: FigmaProps) {
  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.

function Mapper(figma: FigmaProps) {
  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.

function Mapper(figma: FigmaProps) {
  return figma.$visit((node) => {
    if (node.name === "Header") {
      return <h1>{node.$textContent}</h1>;
    } else if (node.name === "Content") {
      return node.$textContent;
    }
  });
}

Tip: 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.

Mapper() examples

The Mapper() function extracts specific content from a Figma design represented by the figma object and uses that content to compose a component.

Tip: The example snippets here are design system-dependent.

Example: a Button component

In this example, the Mapper() function is returning a Button component. It configures the button's attributes based on the provided Figma properties, such as its color, size, and variant.

These properties are mapped from Figma to their respective counterparts in the Button code component so that the button is rendered with the specified configuration defined in the Figma design.

Because Figma properties typically begin with an uppercase letter, while React component props are entirely lowercase, the toLowerCase() method is used in the mapping process to ensure consistency.

function Mapper(figma: FigmaButtonProps) {
  return (
    <Button
      color={figma.Color.toLowerCase()}
      size={figma.Size.toLowerCase()}
      type={figma.Variant.toLowerCase()}
    >
      {figma.$children}
    </Button>
  )
}

This code maps the example properties in this way:

Color: The color property from Figma is converted to lowercase and mapped to the React button's color prop, adhering to the component's expected prop values.
Size: The size property from Figma is converted to lowercase and mapped to the React button's size prop, adhering to the component's expected prop values.
Variant: The button's variant in Figma is also converted to lowercase and mapped to the type prop, ensuring the button's appearance in the UI matches the intended design.

This mapping process is essential for transforming Figma designs into functional React components, maintaining fidelity to the original design while leveraging React's dynamic and interactive capabilities.

To determine which properties are available for a given Figma component, select the component and refer to the Design properties on the right of the Figma UI. All of the properties in the Design tab are available for mapping to React. Here's an example from the MUI Button component which contains additional properties to our Button component from before:

Figma user interface with component properties highlighted

One of the possible outputs would be:

<Button color="primary" size="small" type="contained">Click</Button>

Example: a Hero component

In this example, the Mapper() function is returning a Hero component. It first retrieves the text content of the Figma child layers named Heading and Supporting Text. Then, Mapper() locates the Figma child layer named Navigation centered and returns it as JSX.

If there's a mapped component for the Navigation, it is returned as JSX with appropriate props; otherwise, it is rendered as a plain HTML <div>. Finally, the extracted content is assembled into the Hero component, which is returned by the function.

function Mapper(figma: FigmaHeroSectionProps) {
  // Grab the heading text from the Heading property of the Figma component
  const heading = figma.Heading;

  // Find the first Figma child layer named "Supporting text" and its text content
  const supportingText = figma.$findOneByName("Supporting Text").$textContent;

  // Find the first Figma child layer named "Navigation centered" and return it as JSX
  // If there is a mapping for the Navigation component, it will be returned as JSX
  // for that mapped component like: <Navigation ...props>...</Navigation>.
  // If there is no mapping, it will be returned as plain HTML <div>...</div>
  const navigation = figma.$findOneByName("Navigation");

  return (
    // Put all the pieces together and return the Hero component
    <Hero
      heading={heading}
      supportingText={supportingText}
      navigation={navigation}
    />
  );
}

The output would be:

<Hero 
  heading="Heading text"
  supportingText="Supporting text" 
  navigation={<Navigation ... />} 
/>

Example: getting content from a specific child layer

In general, mapping all children is the most common use case; however, you might have instances where you just want to pull specific layers.

For example, you can fetch all child layers from Figma and return them within the Button component:

function Mapper(figma: FigmaButtonProps) {
  return (
    // Returnns all child layers from figma
    <Button>
      {figma.$children}
    </Button>
  );
}

For which the output would include all children:

<Button>
  <img ... />
  <span>Button Text</span>
  <img ... />
</Button>

However, you can extract only a specific layer, such as just the text content from the Button above.

In this same example, if the decorative elements were already accounted for in the code, you could selectively retrieve other content from the Figma design. In this way, you could precisely map to the code component.

This example specifically gets the text from the second child and returns the Button with just the text:

function Mapper(figma: FigmaButtonProps) {
  // Use the text from the 2nd child ($children is zero indexed).
  const text = figma.$children[1].$textContent

  return (
    // Returns only the text content of the chosen layer
    <Button>
      {text}
    </Button>
  );
}

For which the output would only include the text:

<Button>Button Text</Button>

Another option is to retrieve children by their layer name. The example below extracts only the text from a layer named Label and puts it into the Button component.

function Mapper(figma: FigmaButtonProps) {
  const text = figma.$fineOneByName('Label').$textContent

  return (
    // Returns only the text content of the chosen layer
    <Button>
      {text}
    </Button>
  );
}

For which the output would only include the text:

<Button>Button Label Text</Button>

You can also specify children by reference, so that the content inside them renders in a designated location. In the example below, the Mapper() function retrieves the contents of a Figma layer named Card Contents and renders it within a Card component.

function Mapper(figma: FigmaButtonProps) {
  const contents = figma.$fineOneByName('Card Contents')

  return (
    // Returns only the text content of the chosen layer
    <Card>
      {text}
    </Card>
  );
}

For which the output would only include the text:

<Card>
  <h2>Card contents child 1</h2>
  <p>Card contents child 2</p>
</Card>

Figma nodes and JSX rendering

Each of these functions returns a figma node, which includes various properties.

If you directly return a Figma node, it will be rendered in JSX format. For example:

function Mapper(figma: FigmaProps) {
  return (
    <div>
      {figma.$findOneByName('Navigation')}
    </div>
  )
}

The output would be:

function Mapper(figma: FigmaProps) {
  return (
    <div>
      <Navigation ... />
    </div>
  )
}

If the layer with name Navigation is not mapped to a component, the node will be converted to JSX, as in:

function Mapper(figma: FigmaProps) {
  return (
    <div>
      <div>...</div>
    </div>
  )
}

However, if you specify a text layer, such as using $textContent, like this:

function Mapper(figma: FigmaProps) {
  return (
    <div>
      {figma.$findOneByName('Navigation').$textContent}
    </div>
  )
}

In this case, the output would be the string content of that layer, for instance:

function Mapper(figma: FigmaProps) {
  return (
    <div>
      About Us
    </div>
  )
}

Whenever you return a node within JSX, for example:

function Mapper(figma: FigmaProps) {
  return (
    <div>
      {figma.$findOneByName('dialog')}
    </div>
  )
}

It will be rendered as JSX, as the plugin integrates the node directly into the JSX.

The key takeways are:

If you omit .$textContent at the end, the result will be transformed into DOM nodes.
figma.$children also returns nodes, meaning that whatever is contained within that component will be converted into code.