Components Config

React components can be imported and exposed in Overlay via the .overlay/components.jsonc file.

INFO

When using Shadcn/ui, you can automatically generate the components.jsonc file via the editor interface. Custom React components can be registered too, by hand or with an AI assistant — see Importing components.

TIP

We recommend you to commit this file to share Overlay component mappings with collaborators. If you prefer not to, add .overlay to your .gitignore.

Root structure

jsonc

{
  "components": [
    // component entries go here
  ],
  "iconLibraries": [
    // icon library entries go here
  ],
}

components is an array of component entries. iconLibraries (see below) declares whole icon packages instead of individual components. At least one of the two must be present.

Component entries

Each entry can be written as a string shorthand or an object for more control.

String shorthand

The simplest form — just the relative path to the component file.

jsonc

{
  "components": [
    "src/components/Button.tsx", // default export, name = "Button"
    "src/components/Card.tsx:CardHeader", // named export "CardHeader"
  ],
}

The format for named exports is "path/to/file.tsx:ExportName".

Name resolution:

Default export → name derived from filename (e.g. Button.tsx → "Button")
Named export → name taken from the export identifier (e.g. CardHeader)

Object form

Use the object form when you need to configure props.

jsonc

{
  "components": [
    {
      "source": "components/ui/button.tsx:Button",
      "props": {
        "children": {
          "type": "string",
          "default": "Button",
        },
        "variant": {
          "type": "string",
          "enum": [
            "default",
            "destructive",
            "outline",
            "secondary",
            "ghost",
            "link",
          ],
        },
        "size": {
          "type": "string",
          "enum": ["default", "sm", "lg", "icon"],
        },
        "disabled": {
          "type": "boolean",
        },
      },
    },
  ],
}

Fields

Field	Required	Type	Description
`source`	Yes	`string`	Relative path to the component file from the workspace root
`export`	No	`string`	Export name to use. Defaults to `"default"`
`props`	No	`object`	Prop definitions — see Props configuration

Props configuration

The props field lets you define the props shown in Overlay's props panel. Each key is a prop name, and the value is either a shorthand default or a detailed config object.

Shorthand defaults

Pass a literal value to set the prop type and default in one step. The type is inferred automatically.

jsonc

{
  "props": {
    "variant": "primary", // type: string, default: "primary"
    "disabled": false, // type: boolean, default: false
    "count": 0, // type: number, default: 0
  },
}

Detailed config

Use an object to specify the type, allowed values, default, and description explicitly.

jsonc

{
  "props": {
    "size": {
      "type": "string",
      "enum": ["sm", "md", "lg"],
      "default": "md",
      "description": "Controls the size of the component",
    },
    "disabled": {
      "type": "boolean",
      "default": false,
      "description": "Disables interaction",
    },
  },
}

Prop config fields

Field	Type	Description
`type`	`"string"` \| `"number"` \| `"boolean"` \| `"ReactNode"`	Prop type. Inferred from `default` if omitted. Use `"ReactNode"` for slot/children props
`enum`	`string[]`	Restricts the prop to a fixed set of string values
`default`	`string \| number \| boolean \| null`	Default value shown in the props panel
`description`	`string`	Helper text shown alongside the prop

Full example

jsonc

// File generated with Overlay Studio, a code-first UI design editor.
// Learn more: https://overlay.studio

{
  "components": [
    // Simple default export — name derived from filename
    "src/components/Badge.tsx",

    // Named export using string shorthand
    "src/components/Card.tsx:CardHeader",

    // Full object form with props
    {
      "source": "src/components/Button.tsx",
      "export": "Button",
      "props": {
        "children": { "default": "Click me" },
        "variant": {
          "type": "string",
          "enum": ["primary", "secondary", "ghost"],
          "default": "primary",
        },
        "disabled": false,
      },
    },
  ],
}

TIP

You rarely need to write this file by hand. Overlay can generate entries for you — see Importing components for the Shadcn/ui auto-import and the register-component MCP prompt that lets an AI assistant fill this file in for you.

Icon libraries

Alongside components, .overlay/components.jsonc can declare iconLibraries. Each entry bundles a whole icon set at once and exposes it to designs through a JSX namespace, e.g. <Lucide.ArrowRight />, instead of registering icons one by one. Once configured, icons show up in their own Icons tab in the editor's left panel, where you can browse the whole package visually and drop any icon onto the canvas — no need to remember its name.

jsonc

{
  "iconLibraries": [
    // Shorthand: a known preset id. Expands to that library's namespace and
    // per-icon props (see the table below). Simplest form for popular libraries.
    "lucide-react",

    // Preset + overrides. Use the object form with `preset` when you need to add
    // something the bare string can't carry (e.g. `resolveFrom` in a monorepo)
    // while still getting the template. Sibling fields override the preset;
    // `props` are merged per key.
    {
      "preset": "lucide-react",
      "resolveFrom": "packages/design-system", // where to resolve the package from
      "namespace": "Icons", // override the preset's default namespace
      "props": { "size": 16 }, // override one prop, keep the rest of the preset
    },

    // Raw npm package, no template — you configure the namespace and props.
    {
      "package": "some-icons",
      "include": ["ArrowRight", "Star"], // optional subset (smaller bundle)
      "props": { "size": { "type": "number", "default": 24 } },
    },

    // A local folder of icon files, treated like an imported library.
    {
      "path": "src/icons",
      "namespace": "Brand", // optional; defaults to PascalCase of the folder
      "include": ["ArrowRight"], // optional subset, by icon name
      "props": { "className": "string" },
    },
  ],
}

Icons come from exactly one of three sources per entry:

Field	Description
`preset`	A known icon library id (see the table below). Applies the library's built-in namespace, description, and per-icon props; any sibling field overrides the preset, with `props` merged per key.
`package`	An npm package name, resolved from the workspace's `node_modules`. No template is applied — you configure `namespace` and `props` yourself.
`path`	A workspace-relative folder of local icon files. Each file becomes one icon, so a project can point Overlay at its own icon folder and have it behave like an imported library.

A bare string entry ("lucide-react") is shorthand: if it matches a known preset id it's treated as { "preset": "lucide-react" }, otherwise as { "package": "lucide-react" }.

Fields

Field	Applies to	Description
`resolveFrom`	`package` only	Workspace-relative directory to anchor package resolution at. In a monorepo with an isolated `node_modules` layout (e.g. pnpm), a dependency declared by a sub-package may not be linked into the root `node_modules`; point `resolveFrom` at the sub-package that owns it (e.g. `packages/design-system`) so resolution starts there instead.
`namespace`	all	JSX namespace used to reference icons (`<Namespace.IconName />`). Must be a PascalCase identifier. Defaults to the PascalCase of the package name (`lucide-react` → `LucideReact`) or folder name for the `path` form.
`include`	all	Optional subset of icon names to bundle (tree-shaken, smaller bundle). Defaults to every export of the package, or every icon file in the folder for the `path` form.
`description`	all	Optional description surfaced to the design agent.
`props`	all	Shared prop configuration applied to every icon in the library (e.g. `size`, `strokeWidth`). Same shape as component props.

Built-in presets

A preset (or a bare string that matches one) applies a built-in template: the JSX namespace, a description for the design agent, and a per-icon prop schema. Every field is overridable on the entry.

Preset id (string)	Namespace	Preset props
`lucide-react`	`Lucide`	`size` (24), `color` (`currentColor`), `strokeWidth` (2), `className`
`@tabler/icons-react`	`Tabler`	`size` (24), `color` (`currentColor`), `stroke` (2), `className`
`@phosphor-icons/react`	`Phosphor`	`size` (24), `color` (`currentColor`), `weight` (enum: thin/light/regular/bold/fill/duotone, default `regular`), `mirrored` (false), `className`
`react-feather`	`Feather`	`size` (24), `color` (`currentColor`), `strokeWidth` (2), `className`
`@radix-ui/react-icons`	`RadixIcons`	`color` (`currentColor`), `className`

INFO

Need help configuring a library? Reach out to us for support.

Local icon folders

For the path form, each file in the folder becomes one icon, named by its file name in PascalCase (arrow-right.tsx → ArrowRight). A file contributes an icon when it default-exports its component, or exports a value named after the file; index.* barrels, *.d.ts, and *.test/*.spec/*.stories files are ignored, as is any file with no usable export. Editing, adding, or removing icon files rebuilds the library automatically.

Quickstart

Overlay MCP

Components Config

Root structure

Component entries

String shorthand

Object form

Fields

Props configuration

Shorthand defaults

Detailed config

Prop config fields

Full example

Icon libraries

Fields

Built-in presets

Local icon folders

Components Config ​

Root structure ​

Component entries ​

String shorthand ​

Object form ​

Fields ​

Props configuration ​

Shorthand defaults ​

Detailed config ​

Prop config fields ​

Full example ​

Icon libraries ​

Fields ​

Built-in presets ​

Local icon folders ​

Components Config

Root structure

Component entries

String shorthand

Object form

Fields

Props configuration

Shorthand defaults

Detailed config

Prop config fields

Full example

Icon libraries

Fields

Built-in presets

Local icon folders