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.

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.

Control example

{
    '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

Property	Type	Description
location		This 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.
onmoved		This 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

Property	Type	Description
x	number, formula	Determines the relative x location. Relative meaning 0 is the far left of the shapes bounding box, 1 is the far right.
y	number, formula	Determines the relative y location. Relative meaning 0 is the top border of the shapes bounding box, 1 is the bottom.

Constraint - Path

Property	Type	Description
type	'Path'
points		The 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

Property	Type	Description
type	'area'
x	number, formula	Determines the minimum x value that is an acceptable location for the given controls.
y	number, formula	Determines the minimum y value that is an acceptable location for the given controls.
w	number, formula	The width of the bounding box for the control (number or formula that evaluates to a number).
h	number, formula	The 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

Property	Type	Description
name	string	The internal name of the field, used in formulas.
label	string, TranslatableString	The label displayed when the shape property is shown in the editor.
type	number, string, color, date, boolean, array, object, formula (optional)	The type of data this field stores.
default	boolean, number, string, formula	The 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

Property	Type	Description
condition	formula	The condition checked for the constraint, which fails when this evaluates to false.
resolution	number, string, formula (optional)	The value used to resolve this constraint when it fails.
message	string, TranslatableString (optional)	The message shown to the user when the constraint fails.

Types

Property Type	Description	Example
boolean	True or false.	true false
number	A number value, including both integers and decimal values.	5 -3 3.14
string	A text value.	"ABC" "123-456-7890"
color	A color value, constructed using color functions or a hex color.	"=RGB(255, 0, 0)" "#ff0000"
date	A date value, constructed using date functions.	"=DATE(2019, 1, 1)"
picklist	A 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.
array	Multiple data values supplied as an array. Can be constructed using array functions.	"=ARRAY(1, 2, 3)"
object	A collection of key-value pairs. Can be constructed using object functions.	'=OBJECT("A", 1, "B", 2)'
formula	Allows 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.