in beta
for developers
With the Builder Figma plugin, you can use Visual Copilot to map your Figma designs to your code components.
As an example, suppose you have a design system in Figma and a set of components in code that correspond to the designs in Figma. With Visual Copilot, you can map these components to each other and generate quality code.
The image below shows a design and its corresponding code, which component mapping can help you achieve.
To get the most out of this document, you should:
- Have a Next.js, Remix, or React with Vite app ready with React components.
- Have a Builder Space.
- Have design components in Figma.
- In Figma, open the Builder Figma plugin.
- Click the Login button that displays on the bottom left of the plugin.
- When prompted in the browser, choose the Space you want to authorize access to.
For details on the plugin, read Importing from Figma with Visual Copilot. The video below shows logging in from Figma.
1. Back in Figma, select the design component you'd like to import to Builder.
2. When you have a component selected in Figma, the plugin displays a prompt stating that there are components found in your selection. Click the Map button.
3. To map your components, you must be connected to Builder Devtools. If your app isn't connected to Devtools, the plugin will prompt you to connect Builder Devtools. In this case, follow the instructions on the screen for installing (npm init builder.io@latest and then npm run dev). Note that Devtools might take a moment to boot up.
4. When Devtools is successfully running, the Builder Figma plugin message changes to "Devtools connected", with a green circle beside it.
5. Open http://localhost:####, where #### is your port, in your browser.
6. In the browser, at the Devtools welcome screen, click the Let's get started button.
7. In the prompt that opens for authorizing access, choose the Space you'd like to use and click the Authorize button. Make sure you authorize the same Space for Devtools as you did for the Figma plugin.
8. If you are using a React with Vite app, set up a new route in your application. The route should have a path equal to /builder-demo and the element set to the BuilderPage component imported from your builder.tsx file. This ensures that your React Vite app can render the Builder components correctly.
The video below shows installing Builder Devtools and automatically integrating an app with Builder.
For React Vite: Below is a screenshot showing the final step UI specifically for a React with Vite app.
For more information on Devtools, read Using Builder Devtools for Automated Integration.
To map your components in the Builder plugin in Figma, Devtools must be connected as outlined in the previous section.
Tip: Any components the plugin finds are listed in the plugin dialogue. If none are listed, make sure your design components are selected and that you're running Devtools, per the previous section.
1. With your Figma design selected, click the Map button to let the plugin search for any components in your code that might be matches for your Figma designs. Alternatively, you can select them individually by selecting the appropriate code component in the drop-down on the right side of the plugin dialogue.
2. Click on any component listed on the left of the plugin dialogue to display the generated mapping function and inspect the code. Check the code for the mapping to discern exactly what the plugin is mapping and make any necessary edits. For available mapping functions, read Visual Copilot: Mapping Functions.
If your code components aren't showing up in the plugin, make sure that Devtools is running and that the code components you want to map are exported inside your project.
The video below shows where the code components should be listed, to the right of the plugin dialogue under the Code Components section in the Design System tab.
3. When all components are mapped, go to the Export tab and click the Generate Code button to open Builder.
4. In Builder, the design component now renders in the Visual Editor. Click the Generate button to generate code.
For more information on Devtools, read Using Builder Devtools for Automated Integration.
Tip: If you want to add more design components, you must be logged in and running Devtools. If you've already installed Devtools (with npm init builder.io@latest, as earlier in this document), any time you have the dev server running, Devtools is also running. You can confirm this by checking the Devtools status in the Builder Figma plugin.
The image below shows a Figma design that has been mapped to a code component, imported into Builder, and code generated from the design.
To map components in your codebase, they need to be discoverable by Builder's Devtools. That means you must export your components from any JavaScript or TypeScript file in your code, and (ideally) define their prop types in TypeScript or JSDoc types.
Additionally, you must make sure the plugin has the correct Public API Key and that the model names match.
Provided components are properly exported, the plugin can detect components in the following types of files:
.js.jsx.ts.tsx
In order for the plugin to detect library components, always make sure to export the components you want to map from one of the file types listed earlier in this section.
As a best practice, export the component and use types for props:
// ✅
export function MyComponent(props: { title: string }) {
return ...
}
// ✅
export const MyOtherComponent = () => ...It's also acceptable to export the component later in your file:
type MyProps = { title: string }
const MyComponent = (props: MyProps) => ...
// ✅
export default MyComponent;You must always export the components you want to map. If you do not export them, they do not show up in the plugin. As an example, notice that this component is never exported, so it will not work:
// 🚩 doesn't work, needs to be exported!
function MyComponent() { ... }The plugin operates optimally with TypeScript, enhancing its ability to map your Figma designs to the respective code components efficiently. Because of this, we recommend that you always define types for your component props.
// ✅
export function MyComponent(props: { title: string }) {
return ...
}
// ✅
type MyProps = { title: string }
export function MyComponent(props: MyProps) {
return ...
}While JavaScript without TypeScript is compatible, adding types to your props is ideal for the Builder's automapper to function most effectively:
/**
* @param {Object} props
* @param {string} props.title
* @param {number} props.enabled
* @param {number} props.count
*/
export function MyComponent(props) {
return ...
}When integrating code into your project from libraries like shadcn, the Builder Figma plugin works out of the box because it recognizes components that are defined and exported directly from the code. However, if you're using components from a package that aren't explicitly present in your codebase, you can still map them by re-exporting as below:
// src/components.tsx
export { Button, Card, TextField } from '@mui/material'
export { DatePicker } from 'antd';The example shows a file called components.tsx — though the actual file name doesn't matter — and exports components from libraries. By being exported in this way, these components are discoverable by Builder's Devtools.
Note: Be sure to export each component you want to map. In the above example, only Button, Card, TextField, and DatePicker will be mappable. Export globs; for example, export * from 'package', are not currently supported.
If you get a message that there's an API Key mismatch, it means that the plugin and Devtools (by way of your codebase) are using different API keys.
To confirm that you're using the correct Public API Key, check that the Public API Key in your codebase and the Public API Key in Builder are the same.
- In Builder, press
Cmd/Ctrl + kto open the Command Palette. - Search for "API" and select your API Key to copy it.
- Paste the Public API Key into the dialogue in the Figma Plugin.
- In your code, copy the Public API Key and paste it into the dialogue.
- Click the Refresh button.
If you get a message that there's a model name mismatch, it means that the Builder model name and the code component name in your codebase aren't the same.
To confirm that you're using the correct model names, provide them to the Figma Plugin dialogue.
- In Builder, go to Models.
- Open the model in question and go to Advanced.
- Copy the Unique Identifier and paste it in the Builder Figma Plugin dialogue.
- Go to the component in your codebase, copy its name, and paste it in the dialogue.
- Click the Refresh button.
When using Builder Devtools with component mapping, a new route called figma imports is generated in your project so you can access imported Figma components.
This workflow assumes you are developing on localhost. To enable access for users who are not running Devtools locally, you must update the Preview URL in Builder for the Figma Imports model.
- Using the techniques outlined in this document, map at least one Figma design to a code component in your project. After you've successfully mapped at least one component, a model named Figma Imports model displays in Builder and a route is added to your project.
- Deploy the project to a production environment.
- Go to Models in Builder and update the Preview URL for the Figma Imports model in Builder to match the production URL format; for example,
yoursite.com/figma-imports. This makes sure that users accessing the Figma components without running Devtools locally can use the imported components.
The video below shows going to the Models section of Builder and selecting the Figma Imports model. Note that you won't find that model listed if you haven't completed at least one Figma import using component mapping.
When you open the model, edit the Preview URL field so that others can use the newly mapped component.
This section covered Preview URLs specifically for Figma Imports. For more information on Preview URLs in other use cases, visit Editing and Previewing Your Site.
Certain parts of the Visual Copilot workflow use AI, for more information, visit How Builder Uses AI.
