Layers

Background Layer

The background layer is a special layer that always exists at index 0 in the layer stack. It fills the entire canvas and can display a solid color, image, video, 3D content, or shader.

Special Behavior

Always exists - Every composition has exactly one background layer at index 0
Cannot be deleted - The background layer persists even when cleared
Fills canvas - Ignores transform position/rotation, always fills the artboard
Shared fill model - Use fill for solid, linear, or radial gradient fills; solidColor remains for compatibility

Solid Color Example

background-solid.json

{
  "type": "background",
  "id": "background",
  "name": "Background",
  "visible": true,
  "locked": false,
  "contentType": "solid",
  "fill": {
    "type": "solid",
    "color": "#1a1a1a",
    "opacity": 1
  },
  "solidColor": "#1a1a1a",
  "transform": {
    "x": 0,
    "y": 0,
    "width": 1,
    "height": 1,
    "rotation": 0,
    "opacity": 1
  }
}

Linear Gradient Example

background-gradient.json

{
  "type": "background",
  "id": "background",
  "name": "Background",
  "visible": true,
  "locked": false,
  "contentType": "solid",
  "fill": {
    "type": "linear",
    "angle": 135,
    "stops": [
      { "color": "#7c3aed", "opacity": 1, "position": 0 },
      { "color": "#22d3ee", "opacity": 1, "position": 1 }
    ]
  },
  "solidColor": "#7c3aed",
  "transform": { ... }
}

Radial Gradient Example

background-radial-gradient.json

{
  "type": "background",
  "id": "background",
  "name": "Background",
  "visible": true,
  "locked": false,
  "contentType": "solid",
  "fill": {
    "type": "radial",
    "center": { "x": 0.35, "y": 0.4 },
    "radius": 0.9,
    "stops": [
      { "color": "#f8fafc", "opacity": 1, "position": 0 },
      { "color": "#0f172a", "opacity": 1, "position": 1 }
    ]
  },
  "solidColor": "#f8fafc",
  "transform": { ... }
}

Image Background Example

background-image.json

{
  "type": "background",
  "id": "background",
  "name": "Background",
  "visible": true,
  "locked": false,
  "contentType": "image",
  "fill": {
    "type": "solid",
    "color": "#1a1a1a",
    "opacity": 1
  },
  "solidColor": "#1a1a1a",
  "inputMedia": {
    "mediaUrl": "https://example.com/background.jpg",
    "objectFit": "cover"
  },
  "transform": { ... }
}

3D Background Example

background-3d.json

{
  "type": "background",
  "id": "background",
  "name": "Background",
  "visible": true,
  "locked": false,
  "contentType": "3d",
  "fill": {
    "type": "solid",
    "color": "#1a1a1a",
    "opacity": 1
  },
  "solidColor": "#1a1a1a",
  "input3D": {
    "inputType": "shape",
    "shape": "sphere",
    "color": "#3b82f6",
    "autoRotate": true
  },
  "transform": { ... }
}

Properties

Property	Type	Description
`contentType`	string	"solid" \| "image" \| "video" \| "3d" \| "shader"
`fill`	object	Shared fill descriptor (supports `{ type: "solid", color, opacity }`, `{ type: "linear", angle, stops }`, and `{ type: "radial", center, radius, stops }`; gradients support 2-8 stops)
`solidColor`	string	Legacy solid color fallback (kept for URL/state compatibility)
`input3D`	object	3D settings when contentType is "3d"
`inputMedia`	object	Media settings when contentType is "image" or "video"
`inputShader`	object	Shader settings when contentType is "shader"

Content Types

solid

Solid / Gradient

Solid, linear gradient, or radial gradient fill using the shared fill object

image

Image

Static image (JPG, PNG, WebP) as background

video

Video

Video file playing as animated background

3d

GLTF model, primitive shape, or SVG extrusion

shader

Shader

Procedural shader animation

Input Media Settings

When contentType is "image" or "video", use the inputMedia object:

Property	Type	Description
`mediaUrl`	string	URL of the media file
`objectFit`	string	"cover" \| "contain" \| "stretch"
`brightness`	number	Brightness adjustment (0-2, 1 = normal)
`contrast`	number	Contrast adjustment (0-2, 1 = normal)
`saturation`	number	Saturation adjustment (0-2, 1 = normal)

Input 3D Settings

When contentType is "3d", use the input3D object. See the 3D Layer documentation for full details.