Batch Operations

Batch operations allow you to create, update, or manipulate multiple elements in a single MCP call, with features like client-specified IDs, nested children, and optimized performance.

Client-Specified IDs

Pre-assign element IDs when creating elements for easy reference in subsequent operations.

Why Use Client IDs?

• Predictable References - Know element IDs before they're created
• Batch Operations - Create multiple elements, then update them all
• Parent-Child Relationships - Build hierarchies with known IDs
• Automation - Maintain consistent IDs across generated designs

ID Validation Rules

• Length: 1-128 characters
• Allowed Characters: Letters, numbers, hyphens, underscores (a-z, A-Z, 0-9, -, _)
• Reserved Keywords: Cannot use: root, document, canvas, selection, viewport, workspace, layer, artboard, null, undefined
• Uniqueness: Must be unique within the document

Example: Building a Card

# Create frame with known ID
create_frame({"id": "card-001", "x": 100, "y": 100, "width": 320, "height": 200})

# Add title (nested inside card)
create_text({
  "id": "card-001-title",
  "text": "Card Title",
  "parentId": "card-001",
  "x": 16,
  "y": 16
})

# Add body (nested inside card)
create_text({
  "id": "card-001-body",
  "text": "Card content here",
  "parentId": "card-001",
  "x": 16,
  "y": 50
})

# Later: Update specific part
update_element({
  "id": "card-001-title",
  "props": {"text": "Updated Title"}
})

Nested Children

Create entire element hierarchies in a single operation using the children parameter.

Features

• Depth Support: Up to 10 levels of nesting
• Relative Positioning: Child coordinates are relative to parent
• Automatic IDs: Auto-generated if not specified
• Single Transaction: All elements created atomically

Example: Nested Button

create_frame({
  "id": "button",
  "x": 100,
  "y": 200,
  "width": 200,
  "height": 48,
  "borderRadius": 8,
  "fills": [{"type": "solid", "color": "#007AFF"}],
  "children": [
    {
      "type": "text",
      "id": "button-label",
      "text": "Click Me",
      "x": 60,
      "y": 14,
      "props": {
        "fontSize": 16,
        "fontWeight": "600",
        "textColor": "#FFFFFF"
      }
    },
    {
      "type": "icon",
      "id": "button-icon",
      "name": "arrow-right",
      "x": 160,
      "y": 12,
      "size": 24,
      "color": "#FFFFFF"
    }
  ]
})

Limits

• Max Elements Per Operation: 1000 total
• Max Children Per Element: 500 direct children
• Max Nesting Depth: 10 levels

Response Format Options

Control response payload size with the responseFormat parameter.

minimal (Default)

Smallest payload - just success status, ID, and count

{
  "success": true,
  "id": "element-001",
  "elementCount": 1
}

full

Complete element data included in response

{
  "success": true,
  "id": "element-001",
  "element": {
    "id": "element-001",
    "type": "rectangle",
    "x": 100,
    "y": 100,
    "width": 200,
    "height": 200,
    "fills": [{"type": "solid", "color": "#FF0000"}]
  },
  "elementCount": 1
}

ids_only

Just the array of created element IDs

{
  "success": true,
  "ids": ["element-001", "element-002", "element-003"]
}

Usage

create_rectangle({
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 200,
  "responseFormat": "full"  // or "minimal" or "ids_only"
})

Batch Create Examples

Grid of Squares

Claude will:

• Calculate positions for 25 squares
• Create all 25 in batch operation
• Use client IDs like "square-0-0", "square-0-1", etc.

Color Palette

Claude will:

• Create 8 rectangles with specified colors
• Arrange them horizontally
• Add text labels below each

Social Media Icons

Claude will:

• Insert 5 icons in single operation
• Space them evenly
• Use consistent sizing

Batch Update Examples

Change All Colors

Claude will:

• Query all elements
• Filter for rectangles
• Update each with new color

Align Multiple Elements

Claude will:

• Use client IDs to reference elements
• Calculate new positions
• Update all positions in batch

Performance Optimizations

Batch Parent Updates

When creating multiple children in same parent:

• Before: Parent updated N times (once per child)
• After: Parent updated once at the end
• Benefit: Faster creation of complex hierarchies

Minimal Response Format

For bulk operations:

• Use responseFormat: "minimal" or "ids_only"
• Reduces network payload
• Faster for operations creating 100+ elements

Namespace Lazy Loading

Tools load on-demand:

• 5 default namespaces active (30-40 tools)
• 13 additional namespaces load when needed
• Faster initial connection

Error Handling

Validation Errors

Operations fail with descriptive errors if:

• Client ID invalid (wrong characters, reserved keyword)
• Element count exceeds limits (1000 per operation)
• Nesting depth exceeds 10 levels
• Duplicate ID specified

Rollback on Failure

If batch operation fails partway:

• All created elements are automatically deleted
• Document returns to pre-operation state
• No partial/broken structures left behind

Best Practices

• Use Client IDs - For elements you'll reference later
• Nested Children - For tightly coupled elements (buttons, cards)
• Batch Operations - Create multiple similar elements in one call
• Minimal Responses - For bulk operations (>10 elements)
• Clear Naming - Use descriptive client IDs (button-submit, card-hero)
• Stay Under Limits - Max 1000 elements per operation

Related Topics

• Composite UI Tools - High-level components
• Screen Templates - Complete screens
• Namespace System - Tool organization