Shape data can be defined on a custom shape to allow users to configure the data used by the custom shape.
Shape data can be used in any formula within the shape, using the syntax @PropertyName.
For more information about Lucidchart's formula system, see the formulas page.

Shape controls

Controls directly modify the linked dynamic properties of a shape – these can be used to modify the shapes properties or geometry. They use the location of the control (represented by ControlX and ControlY as built-in variables within shape controls) within the shape’s bounding box as the thing that powers these changes.

📘

The shape controls only exist inside the Lucidchart editor, in the advanced shape editor preview, the controls will not render or be interactable.

For example, in the above shape, the left spatial control is about 0.3 (30%) of the width of the shape. If I move it to look like this:

The built-in variables representing the location of the control become ControlX = 0.6, ControlY=0.4 which updates my dynamic properties to also have that value, causing the stencil to re-evaluate its geometry.

📘

For all control locations, the points are relative to the shape’s bounding box (0 - 1). Absolute points are not supported at this time.

{
    'uri': 'control',
    'schema': {
        'type': 'object',
        'required': ['location', 'onmove'],
        'properties': {
            // all values here are relative to shape bounds
            'location': {'x': {'$ref': 'numberFormula'}, 'y': {'$ref': 'numberFormula'}},
            // defaults to shape bounding box if undefined
            'constraint': {
                'oneOf': [{'$ref': 'areaConstraint'}, {'$ref': 'pathConstraint'}],
            },
            'onmove': {'type': 'array', 'items': {'$ref': 'setPropertyAction'}},
        },
    },
},
{
    'uri': 'pathConstraint',
    'schema': {
        'type': 'object',
        'required': ['type', 'points'],
        'properties': {
            'type': {'enum': ['path']},
            'points': {'type': 'array', 'items': {'x': {'$ref': 'numberFormula'}, 'y': {'$ref': 'numberFormula'}}},
        },
        'additionalProperties': false,
    },
},
{
    'uri': 'areaConstraint',
    'schema': {
        'type': 'object',
        'required': ['type', 'x', 'y', 'w', 'h'],
        'properties': {
            'type': {'enum': ['area']},
            'x': {'$ref': 'numberFormula'},
            'y': {'$ref': 'numberFormula'},
            'w': {'$ref': 'numberFormula'},
            'h': {'$ref': 'numberFormula'},
        },
        'additionalProperties': false,
    },
},
{
    'uri': 'formulaDefinition',
    'schema': {
        'type': 'object',
        'required': ['name', 'value'],
        'properties': {
            'name': {
                'type': 'string',
            },
            'value': {'$ref': 'formula'},
        },
        'additionalProperties': false,
    },
},

Control Schema

Location

Constraint - Path

Constraint - Area

Validation

Controls require that you have a dynamic property whose ‘name’ matches the ‘field’ of the SetPropertyAction.

📘

Shape controls only have access to the localDefs on the stencil, the dynamic shapes on the stencil, and the built in ControlX and ControlY.

ShapeProperty schema

Constraint schema

Types

Constraints

Shape data properties can have an optional list of constraints which restrict the values of data allowed. For example, a percentage field could have a constraint where the value must be less than or equal to 100.

Constraints do not prevent saving shape data, but rather will indicate the value is invalid and allow an optional resolution value, which is used in place of the specified value. In the above example, if the percentage field exceeds 100, the resolution value might be 100 (i.e. if the value were to go above 100, then the resolution value (100) is used instead). If no resolution is provided, the shape will be shown as an error state.