These docs are for v1.0. Click to read the latest docs for v1.2.

Shape data properties

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.

Shape Controls Wide

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:

Shape Controls Narrow

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

PropertyTypeDescription
locationThis is where the control lies on the shape.
constraints(optional)This is where the control is allowed to be moved — essentially the set of points that are valid inputs for this control. If left undefined, defaults to the shape’s bounding box.
onmovedThis is the set of actions to be done when the control is moved. Here is where you can utilize the built-in “ControlX” and “ControlY” variables that represent the new dropped location of the control.

Location

PropertyTypeDescription
xnumber, formulaDetermines the relative x location. Relative meaning 0 is the far left of the shapes bounding box, 1 is the far right.
ynumber, formulaDetermines the relative y location. Relative meaning 0 is the top border of the shapes bounding box, 1 is the bottom.

Constraint - Path

PropertyTypeDescription
type'Path'
pointsThe discrete points that the spatial control is allowed to move in. Essentially the values that ‘ControlX’ and ‘ControlY’ are allowed to be. The x and y values in all of these points are allowed to be numbers or formulas.

Constraint - Area

PropertyTypeDescription
type'area'
xnumber, formulaDetermines the minimum x value that is an acceptable location for the given controls.
ynumber, formulaDetermines the minimum y value that is an acceptable location for the given controls.
wnumber, formulaThe width of the bounding box for the control (number or formula that evaluates to a number).
hnumber, formulaThe height of the bounding box for the control (number or formula that evaluates to a number).

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

PropertyTypeDescription
namestringThe internal name of the field, used in formulas.
labelstring, TranslatableStringThe label displayed when the shape property is shown in the editor.
typenumber, string, color, date, boolean, array, object, formula (optional)The type of data this field stores.
defaultboolean, number, string, formulaThe default value for the field. This can be a formula or a constant value.
constraints[Constraint (optional)Constraints which determine whether or not the property is valid.

Constraint schema

PropertyTypeDescription
conditionformulaThe condition checked for the constraint, which fails when this evaluates to false.
resolutionnumber, string, formula (optional)The value used to resolve this constraint when it fails.
messagestring, TranslatableString (optional)The message shown to the user when the constraint fails.

Types

Property TypeDescriptionExample
booleanTrue or false.true
false
numberA number value, including both integers and decimal values.5
-3
3.14
stringA text value."ABC"
"123-456-7890"
colorA color value, constructed using color functions or a hex color."=RGB(255, 0, 0)"
"#ff0000"
dateA date value, constructed using date functions."=DATE(2019, 1, 1)"
picklistA value selected from a list of possible values, displayed in the editor as a picklist. The value must be one of the available values in the.picklist.
arrayMultiple data values supplied as an array. Can be constructed using array functions."=ARRAY(1, 2, 3)"
objectA collection of key-value pairs. Can be constructed using object functions.'=OBJECT("A", 1, "B", 2)'
formulaAllows any formula value."=1+2"

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.