Using Custom Code Components

When using Locofy CLI, you can map Figma components to your existing custom component library so generated screens use your real code—not generic placeholders.

This is especially useful when you already have a design system in your codebase and want Locofy to respect it during locofy convert and Interactive Mode.

Working with your design team

Locofy CLI and MCP are built for developers. You handle the codebase—locofy init, locofy push, and generating code from a Figma URL. But custom components and Figma component setup also require work inside Figma, which you may not have access to or may not be familiar with.

Note: You do not need to become a Figma expert. Share the designer checklist below with whoever owns the design file, then focus on the developer steps in your terminal or IDE.

What you do (developer)

Configure and push your component library from your project root (locofy init, then locofy push).
Define mappings in locofy.config.json—component paths, figmaComponentName, and prop names.
Share the config with your designer so Figma component names and properties stay aligned with your code.
Generate code with locofy convert or MCP once components are mapped.

What your designer does (Figma)

Ask your designer (or design lead) to complete these steps in the Figma file:

Open the file in Figma Design Mode — Design Mode is where layouts are created and edited. The Locofy plugin runs the full custom-component and mapping flow here. Dev Mode is for inspection only and is not sufficient for this setup.
Open the Locofy plugin — In Design Mode, go to Actions (⌘/Ctrl + K) → Plugins → search for Locofy.
Pull your pushed components — After you run locofy push, your designer clicks I have completed all the steps in the plugin so your code components appear for mapping.
Map components and props — Match Figma components to your code components and wire up prop mapping in the plugin (or confirm mappings you defined in locofy.config.json).
Structure designs correctly — Reusable UI should be built as Figma components with text, boolean, and variant properties—not flat frames. Share the Figma Components guide with your designer.

Don't have Figma access?

You can still push components and define mappings in locofy.config.json from your repo. For plugin-side mapping and design validation, coordinate with your designer—they only need to run the Locofy plugin in Design Mode on the shared Figma file. Generation via CLI or MCP only requires the Figma URL and your Locofy account's Figma connection.

CLI workflow for custom components

Your steps (terminal):

Install and log in to the CLI — see Quickstart.
Run locofy init from your project root to create locofy.config.json.
Configure your component library in locofy.config.json.
Run locofy push to upload components from your local codebase to Locofy.
Ask your designer to open the Locofy plugin in Figma Design Mode and click I have completed all the steps so pushed components appear for mapping.
Generate code with locofy convert — Locofy uses your mapped components when building screens.

For CLI command details and locofy.config.json structure, see Import components using the Locofy CLI and Configure components.

Note: Connecting and mapping custom components is available on Enterprise plans and legacy annual self-service subscriptions. It is not available on monthly self-service plans (Free, Hobby, Pro) or the 5-day free trial.

How to structure the wrapper component

Importing from GitHub or using Locofy CLI requires a wrapper path in locofy.config.json.

Locofy generates screens and maps your components—it does not automatically wire up your app's global setup. You need a wrapper because generated UI must mount inside a single root that loads what the rest of your app expects: global CSS and design tokens, fonts, Tailwind, and any React context or theme providers your components rely on. Without it, previews and exported code can look unstyled or break when components assume that shared setup is already present.

Currently we support only one wrapper which can be customised to your requirements

Basic Wrapper

The basic wrapper has a single prop for children which it simply returns.

import React from "react";
 
export default function Wrapper({ children }) {
  return children;
}

Importing Custom Styles

You can import your google and custom fonts in your global.css file

body {
  margin: 0;
  line-height: normal;
}
:root {
  /* fonts */
  --font-roboto: Roboto;
  --font-baloo-bhai: "Baloo Bhai";

  /* font sizes */
  --font-size-base: 16px;
  --font-size-xl: 20px;
  --font-size-lg: 18px;
  --font-size-sm: 14px;

  /* Colors */
  --color-darkgray: #999;
  --color-black: #000;

  /* Gaps */
  --gap-xs: 12px;

  /* Paddings */
  --padding-xs: 12px;

  /* Border radiuses */
  --br-xs: 12px;
}

Here you can import your custom styles defined in global.css into the wrapper component so all the components will have access to them.

import React from "react";
import './globals.css';
 
export default function Wrapper({ children }) {
  return children;
}

Add Context or Theme Providers

Here you can define your own Custom Theme or Context Provider and include that in the wrapper component. This way your components

import * as React from "react";
import { createTheme, ThemeProvider } from "@mui/material/styles";
import { green, red } from "@mui/material/colors";

const outerTheme = createTheme({
  palette: {
    primary: {
      main: red[500],
    },
  },
});

const innerTheme = createTheme({
  palette: {
    primary: {
      main: green[500],
    },
  },
});

export default function Wrapper({ children }) {
  return (
    <ThemeProvider theme={outerTheme}>
      <ThemeProvider theme={innerTheme}>
        {children}
      </ThemeProvider>
    </ThemeProvider>
  );
}

Importing Fonts

You can import your google and custom fonts in your global.css file

@import url("https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap");
@import url("https://fonts.googleapis.com/css2?family=Baloo+Bhai:wght@400&display=swap");
@import url("https://fonts.googleapis.com/icon?family=Material+Icons");

@font-face {
  font-family: "Satoshi";
  src: url("/public/Satoshi-Medium.otf");
  font-weight: 500;
}

You can then import the global.css file into your wrapper component

import React from "react";
import './globals.css';
 
export default function Wrapper({ children }) {
  return children;
}

Importing Tailwind v3

You can import your Tailwind classes in index.css file

@tailwind base;
@tailwind components;
@tailwind utilities;
body {
  @apply leading-[normal] m-0;
}
*,
::before,
::after {
  border-width: 0;
}

You need to create a postcss.config.js file. You can view the official Tailwind documentation here.

import tailwindcss from "tailwindcss"
import autoprefixer from "autoprefixer"

export default = {
  plugins: [tailwindcss, autoprefixer],
};

You can then import the index.css file into your wrapper component

import React from "react";
import './index.css';
 
export default function Wrapper({ children }) {
  return children;
}

Importing Tailwind v4

You can import your Tailwind classes in index.css file

@import "tailwindcss/theme.css";
@import "tailwindcss/preflight.css";
@import "tailwindcss/utilities.css";
@config "../tailwind.config.js";

body {
  @apply leading-[normal] m-0;
}
@layer base {
  *,
  ::before,
  ::after {
    border-width: 0;
  }
}

You need to create a postcss.config.js file. You can view the official Tailwind documentation here.

module.exports = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

You can then import the index.css file into your wrapper component

import React from "react";
import './index.css';
 
export default function Wrapper({ children }) {
  return children;
}

What happens during generation

Locofy replaces Figma components with your actual custom component code and wires the correct props automatically when generating screens. If a component isn't auto-mapped, use manual prop mapping to connect it.

What's next

Figma Components — what your designer needs to structure in Figma
Manual prop mapping — connect Figma props to code props
Complex prop mapping (mapFn) — advanced mapping for derived and array data

Using Custom Code Components

On this page