Properties - Metabind

Overview

Properties make your components configurable and reusable. They define the inputs your component accepts and how they appear in the inspector panel. BindJS supports multiple property types, each with its own validation and inspector options.

Property Structure

Every property definition follows this structure:

const properties = {
    propertyName: {
        type: "string",           // Required: property type
        title: "Display Name",    // Optional: shown in inspector
        description: "Help text", // Optional: additional context
        required: false,          // Optional: whether required
        defaultValue: "default",  // Optional: default value
        inspector: { },           // Optional: inspector customization
        validation: { }           // Optional: validation rules
    }
} satisfies ComponentProperties;

String Properties

Text input properties for single or multi-line text.

Basic String

title: {
    type: "string",
    title: "Title"
}

String with Validation

email: {
    type: "string",
    title: "Email Address",
    validation: {
        format: "email",
        minLength: 5,
        maxLength: 100
    }
}

Multi-line String

description: {
    type: "string",
    title: "Description",
    inspector: {
        control: "multiline",
        numberOfLines: 5,
        placeholder: "Enter description..."
    }
}

Markdown String

content: {
    type: "string",
    title: "Content",
    inspector: {
        control: "multiline",
        markdown: true,
        numberOfLines: 10
    }
}

String Options

Option	Type	Description
`type`	`"string"`	Required - Property type
`title`	`string`	Display name in inspector
`description`	`string`	Help text shown below field
`required`	`boolean`	Whether the field is required
`defaultValue`	`string`	Default value
`examples`	`string[]`	Example values
`inspector.control`	`"singleline"` \| `"multiline"`	Input type
`inspector.placeholder`	`string`	Placeholder text
`inspector.markdown`	`boolean`	Enable markdown editing
`inspector.numberOfLines`	`number`	Lines for multiline (default: 3)
`validation.minLength`	`number`	Minimum character length
`validation.maxLength`	`number`	Maximum character length
`validation.pattern`	`string`	Regex pattern to match
`validation.format`	`"text"` \| `"email"` \| `"url"`	Format validation

Number Properties

Numeric input properties with optional min/max validation.

Basic Number

count: {
    type: "number",
    title: "Count"
}

Number with Range

opacity: {
    type: "number",
    title: "Opacity",
    validation: {
        min: 0,
        max: 1
    },
    inspector: {
        step: 0.1
    }
}

Number with Slider

fontSize: {
    type: "number",
    title: "Font Size",
    validation: {
        min: 12,
        max: 72
    },
    inspector: {
        control: "slider",
        step: 1
    }
}

Number Options

Option	Type	Description
`type`	`"number"`	Required - Property type
`title`	`string`	Display name in inspector
`description`	`string`	Help text
`required`	`boolean`	Whether required
`defaultValue`	`number`	Default value
`inspector.control`	`"slider"` \| `"input"`	Input type
`inspector.step`	`number`	Step increment
`inspector.placeholder`	`number`	Placeholder value
`validation.min`	`number`	Minimum value
`validation.max`	`number`	Maximum value

Boolean Properties

Toggle switch properties for true/false values.

Basic Boolean

enabled: {
    type: "boolean",
    title: "Enabled"
}

Boolean with Default

showIcon: {
    type: "boolean",
    title: "Show Icon",
    defaultValue: true
}

Boolean Options

Option	Type	Description
`type`	`"boolean"`	Required - Property type
`title`	`string`	Display name in inspector
`description`	`string`	Help text
`required`	`boolean`	Whether required
`defaultValue`	`boolean`	Default value (true/false)

Enum Properties

Dropdown or segmented control for selecting from predefined options.

Basic Enum

size: {
    type: "enum",
    options: ["small", "medium", "large"],
    title: "Size"
}

Enum with Labels

alignment: {
    type: "enum",
    options: [
        { value: "leading", label: "Left" },
        { value: "center", label: "Center" },
        { value: "trailing", label: "Right" }
    ],
    title: "Alignment"
}

Enum with Icons

icon: {
    type: "enum",
    options: [
        { value: "star", icon: "star.fill" },
        { value: "heart", icon: "heart.fill" },
        { value: "bookmark", icon: "bookmark.fill" }
    ],
    title: "Icon"
}

Segmented Control

variant: {
    type: "enum",
    options: ["primary", "secondary", "tertiary"],
    title: "Variant",
    inspector: {
        control: "segmented"
    }
}

Enum Options

Option	Type	Description
`type`	`"enum"`	Required - Property type
`options`	`string[]` \| `number[]` \| `object[]`	Required - Available options
`title`	`string`	Display name in inspector
`description`	`string`	Help text
`required`	`boolean`	Whether required
`defaultValue`	`string` \| `number`	Default selected value
`inspector.control`	`"segmented"` \| `"dropdown"`	Control type

Array Properties

Properties that accept multiple values.

String Array

tags: {
    type: "array",
    valueType: {
        type: "string"
    },
    title: "Tags",
    validation: {
        minItems: 1,
        maxItems: 10
    }
}

Number Array

ratings: {
    type: "array",
    valueType: {
        type: "number",
        validation: { min: 1, max: 5 }
    },
    title: "Ratings"
}

Array Options

Option	Type	Description
`type`	`"array"`	Required - Property type
`valueType`	`PropertyField`	Required - Type of array items
`title`	`string`	Display name in inspector
`description`	`string`	Help text
`required`	`boolean`	Whether required
`defaultValue`	`any[]`	Default array value
`validation.minItems`	`number`	Minimum number of items
`validation.maxItems`	`number`	Maximum number of items

Asset Properties

Properties for uploading and selecting media assets.

Image Asset

image: {
    type: "asset",
    assetTypes: ["image"],
    title: "Image"
}

Video Asset

video: {
    type: "asset",
    assetTypes: ["video"],
    title: "Video"
}

Multiple Asset Types

media: {
    type: "asset",
    assetTypes: ["image", "video"],
    title: "Media"
}

3D Model Asset

model: {
    type: "asset",
    assetTypes: ["model", "model/usdz", "model/glb"],
    title: "3D Model"
}

Asset Value Structure

Asset properties return values wrapped by their type:

// For image asset
props.image = {
    image: {
        url: "https://example.com/image.jpg"
    }
}

// Usage in component
Image(props.image.image)
    .resizable()
    .frame({ height: 200 })

Asset Options

Option	Type	Description
`type`	`"asset"`	Required - Property type
`assetTypes`	`AssetType[]`	Required - Allowed asset types
`title`	`string`	Display name in inspector
`description`	`string`	Help text
`required`	`boolean`	Whether required

Available Asset Types:

"image" - Image files (jpg, png, gif, etc.)
"video" - Video files (mp4, mov, etc.)
"audio" - Audio files (mp3, wav, etc.)
"model" - 3D model files
"model/usdz" - USDZ format models
"model/glb" - GLB format models

Component Properties

Properties that accept other components as values.

Basic Component

header: {
    type: "component",
    title: "Header Component"
}

Component with Environment

content: {
    type: "component",
    title: "Content",
    environment: {
        theme: "dark",
        size: "large"
    }
}

Component with Restrictions

icon: {
    type: "component",
    title: "Icon",
    allowedComponents: ["IconComponent", "SystemIcon"]
}

Component Options

Option	Type	Description
`type`	`"component"`	Required - Property type
`title`	`string`	Display name in inspector
`description`	`string`	Help text
`required`	`boolean`	Whether required
`environment`	`object`	Environment values for component
`allowedComponents`	`string[]`	Restrict to specific components

Date Properties

Properties for date selection.

Basic Date

publishDate: {
    type: "date",
    title: "Publish Date"
}

Date with Range

eventDate: {
    type: "date",
    title: "Event Date",
    validation: {
        minDate: "2024-01-01",
        maxDate: "2024-12-31"
    }
}

Date Options

Option	Type	Description
`type`	`"date"`	Required - Property type
`title`	`string`	Display name in inspector
`description`	`string`	Help text
`required`	`boolean`	Whether required
`defaultValue`	`string`	Default date (ISO format)
`inspector.placeholder`	`string`	Placeholder text
`validation.minDate`	`string`	Minimum date (ISO format)
`validation.maxDate`	`string`	Maximum date (ISO format)

Group Properties

Properties for nested object structures.

Basic Group

settings: {
    type: "group",
    title: "Settings",
    properties: {
        enabled: {
            type: "boolean",
            title: "Enabled"
        },
        timeout: {
            type: "number",
            title: "Timeout (ms)"
        }
    }
}

Nested Groups

theme: {
    type: "group",
    title: "Theme",
    properties: {
        colors: {
            type: "group",
            title: "Colors",
            properties: {
                primary: { type: "string", title: "Primary" },
                secondary: { type: "string", title: "Secondary" }
            }
        },
        typography: {
            type: "group",
            title: "Typography",
            properties: {
                fontSize: { type: "number", title: "Font Size" },
                fontFamily: { type: "string", title: "Font Family" }
            }
        }
    }
}

Group Options

Option	Type	Description
`type`	`"group"`	Required - Property type
`properties`	`ComponentProperties`	Required - Nested properties
`title`	`string`	Display name in inspector
`description`	`string`	Help text
`required`	`boolean`	Whether required

Inspector Customization

All property types support inspector customization to control how they appear in the editor.

Common Inspector Options

propertyName: {
    type: "string",
    title: "Property Name",
    inspector: {
        showLabel: true,        // Show/hide label
        showDivider: true,      // Show/hide divider
        visible: true,          // Show/hide field
        helpDescription: "..."  // Additional help text
    }
}

Best Practices

1. Use Descriptive Titles

// Good
title: {
    type: "string",
    title: "Card Title"
}

// Avoid
title: {
    type: "string",
    title: "Title"
}

2. Provide Validation

email: {
    type: "string",
    title: "Email",
    validation: {
        format: "email",
        maxLength: 100
    }
}

3. Use Appropriate Controls

// Use slider for bounded numbers
opacity: {
    type: "number",
    validation: { min: 0, max: 1 },
    inspector: { control: "slider", step: 0.1 }
}

// Use segmented for few options
size: {
    type: "enum",
    options: ["small", "medium", "large"],
    inspector: { control: "segmented" }
}

4. Set Defaults in Previews

Don’t use defaultValue in properties unless necessary. Instead, provide defaults in previews:

const previews = [
    Self({ 
        title: "Default Title",  // Provide default here
        size: "medium"
    })
];

5. Name Asset Properties Appropriately

// Single asset - use "asset"
asset: {
    type: "asset",
    assetTypes: ["image"]
}

// Multiple assets - use descriptive names
backgroundImage: {
    type: "asset",
    assetTypes: ["image"]
},
icon: {
    type: "asset",
    assetTypes: ["image"]
}

Complete Example

const properties = {
    title: {
        type: "string",
        title: "Card Title",
        validation: { maxLength: 100 }
    },
    description: {
        type: "string",
        title: "Description",
        inspector: {
            control: "multiline",
            numberOfLines: 3
        }
    },
    image: {
        type: "asset",
        assetTypes: ["image"],
        title: "Card Image"
    },
    variant: {
        type: "enum",
        options: ["default", "featured", "compact"],
        title: "Variant",
        inspector: { control: "segmented" }
    },
    showIcon: {
        type: "boolean",
        title: "Show Icon"
    },
    priority: {
        type: "number",
        title: "Priority",
        validation: { min: 1, max: 10 },
        inspector: { control: "slider" }
    }
} satisfies ComponentProperties;

Next Steps

Core Concepts: Learn how properties fit into components
Quickstart: Build a component with properties
Components: See properties in action

Overview

Guides

AI

Components

Content Editor

Styles

Functions

Modifiers

Types

​Overview

​Property Structure

​String Properties

​Basic String

​String with Validation

​Multi-line String

​Markdown String

​String Options

​Number Properties

​Basic Number

​Number with Range

​Number with Slider

​Number Options

​Boolean Properties

​Basic Boolean

​Boolean with Default

​Boolean Options

​Enum Properties

​Basic Enum

​Enum with Labels

​Enum with Icons

​Segmented Control

​Enum Options

​Array Properties

​String Array

​Number Array

​Array Options

​Asset Properties

​Image Asset

​Video Asset

​Multiple Asset Types

​3D Model Asset

​Asset Value Structure

​Asset Options

​Component Properties

​Basic Component

​Component with Environment

​Component with Restrictions

​Component Options

​Date Properties

​Basic Date

​Date with Range

​Date Options

​Group Properties

​Basic Group

​Nested Groups

​Group Options

​Inspector Customization

​Common Inspector Options

​Best Practices

​1. Use Descriptive Titles

​2. Provide Validation

​3. Use Appropriate Controls

​4. Set Defaults in Previews

​5. Name Asset Properties Appropriately

​Complete Example

​Next Steps

Overview

Property Structure

String Properties

Basic String

String with Validation

Multi-line String

Markdown String

String Options

Number Properties

Basic Number

Number with Range

Number with Slider

Number Options

Boolean Properties

Basic Boolean

Boolean with Default

Boolean Options

Enum Properties

Basic Enum

Enum with Labels

Enum with Icons

Segmented Control

Enum Options

Array Properties

String Array

Number Array

Array Options

Asset Properties

Image Asset

Video Asset

Multiple Asset Types

3D Model Asset

Asset Value Structure

Asset Options

Component Properties

Basic Component

Component with Environment

Component with Restrictions

Component Options

Date Properties

Basic Date

Date with Range

Date Options

Group Properties

Basic Group

Nested Groups

Group Options

Inspector Customization

Common Inspector Options

Best Practices

1. Use Descriptive Titles

2. Provide Validation

3. Use Appropriate Controls

4. Set Defaults in Previews

5. Name Asset Properties Appropriately

Complete Example

Next Steps