Skip to main content

​
Overview

Creates a new instance of an existing component at the specified position. The component must exist in the current document.

​
Parameters

​
componentKey
string
required
Key of the component to instantiate. Get this from get_local_components
​
x
number
required
X position where the instance will be created
​
y
number
required
Y position where the instance will be created

​
Response

Returns information about the created instance:
​
id
string
Unique node identifier for the created instance
​
name
string
Name of the instance (inherited from the component)
​
x
number
X position of the instance
​
y
number
Y position of the instance
​
componentKey
string
Key of the main component this instance references

​
Usage Example

// First, get available components
const components = await get_local_components();
const buttonComponent = components.components.find(
  c => c.name === "Button/Primary"
);

// Create an instance at position (100, 200)
const instance = await create_component_instance({
  componentKey: buttonComponent.key,
  x: 100,
  y: 200
});

console.log(instance);
// {
//   "id": "345:678",
//   "name": "Button/Primary",
//   "x": 100,
//   "y": 200,
//   "componentKey": "abc123def456"
// }

​
Common Use Cases

Rapid Prototyping

Quickly populate designs with component instances

Batch Creation

Create multiple instances programmatically for layouts

Design Automation

Automate repetitive instance placement tasks

Template Generation

Generate templated screens with consistent components

​
Workflow

1

Get components

Use get_local_components to find available components
2

Create instance

Call create_component_instance with the component key and position
3

Customize instance (optional)

Use get_instance_overrides and set_instance_overrides to apply customizations

​
Error Handling

The component key must be valid and from a component in the current document. Using an invalid key will result in an error.
try {
  const instance = await create_component_instance({
    componentKey: "invalid-key",
    x: 0,
    y: 0
  });
} catch (error) {
  console.error("Failed to create instance:", error.message);
  // Error: Component with key 'invalid-key' not found
}

​
Notes

  • The created instance inherits all properties from the main component
  • Position is absolute on the current page
  • The instance can be modified after creation using other tools
  • Component must be from the current document (library components require different handling)

​
Related Tools

Build docs developers (and LLMs) love

Get started for freeTalk to us