Working with Symbols

Symbols allow you to place multiple instances of an item in your project. This can save memory, since all instances of a symbol simply refer to the original item and it can speed up moving around complex objects, since internal properties such as segment lists and gradient positions don't need to be updated with every transformation.

To create a symbol from an item, just pass the item to the new SymbolDefinition(item) constructor. When you create a symbol definition using an item, that item is automatically removed from the document.

To place instances of the symbol in your project, you can call symbolDefinition.place(position) on it, with the position where you want to place it.

For example, lets create a circle shaped path and place a few instances of it:

A placed instance of a symbol is a SymbolItem and can be manipulated like any other Item.

When you select a SymbolItem by setting item.selected to true, Paper.js draws its bounding box. This allows you to see how it has been transformed.

When you create a symbol definition from an item, that item becomes its symbolDefinition.item. Editing the item is reflected in all its SymbolItem instances.