Symbols & Instances

What it’s for

Without symbols, ten copies of a button are ten independent objects — restyling means editing all ten. With a symbol there is one source of truth: the master. Instances stay in sync automatically, so a design change ripples everywhere in one step. Instances are also lightweight — the document stores the master once plus a small reference (id + position + size) per instance.

Create a symbol

Select one or more objects, then right-click → Create Symbol (or the + in the Symbols panel). Your selection becomes the master and is replaced by a single linked instance. From then on you can place more instances that all share that master.

const Y = window.Yappy; Y.clear();
const circ = Y.createCircle(100, 100, 90, 90, { backgroundColor:'#2563eb', fillStyle:'solid' });
const star = Y.createStar(118, 118, 54, 54, 5, { backgroundColor:'#facc15', fillStyle:'solid' });
const symId = Y.createSymbol('Badge', [circ, star]);   // → 1 instance + a master
Y.placeInstance(symId, 260, 100);                      // drop another instance
Y.placeInstance(symId, 420, 100);

The Symbols panel

Open it with Alt+B (or View → Symbols Panel). It lists every symbol with a live thumbnail and an instance count badge. From a card you can:

• Place a new instance (the + button, or double-click the thumbnail).
• Select all instances of a symbol on the canvas (single-click the thumbnail).
• Rename (double-click the name) and delete (🗑 — its instances are detached into editable copies first, so artwork is never lost).
• Redefine the master from the current selection (↻).

Edit in place

Double-click an instance (or right-click → Edit Symbol (in place)) to open the master for editing right where the instance sits. The instance temporarily expands into its editable parts and a breadcrumb appears at the top:

• Done (Enter) — apply your edits to the symbol; every instance updates.
• Cancel (Esc) — discard the edits; the instance is restored unchanged.

Detach (break the link)

Right-click an instance → Detach Instance to turn it into ordinary, independently editable shapes that no longer follow the master. Use this when one copy needs to diverge from the rest.

Recursive symbols (Droste & spirals)

A symbol may contain an instance of itself. Because every instance is drawn from the master, that one nested copy repeats — a picture inside the picture inside the picture. The transform you give the nested instance is what you see repeated: nudge it and you get a receding corridor; shrink and rotate it and you get a logarithmic spiral; place two and you get a branching fractal tree.

Build one by editing the symbol in place (double-click an instance), then placing another instance of the same symbol inside — position, scale and rotate it, and press Done. Recursive drawing switches on automatically, and the card in the Symbols panel gets a ⟳ badge with a Depth field.

Recursion is off by default. Without it, a symbol reached inside itself draws the grey “cyclic” placeholder — the safe behaviour every older document was authored against. Use the ⟳ button on the symbol card to turn it on or off; the button only appears on symbols that actually contain themselves.

const Y = window.Yappy; Y.clear();

// a box, made into a symbol
const box = Y.createRectangle(100, 100, 200, 200, { backgroundColor: '#2563eb', fillStyle: 'solid' });
const sym = Y.createSymbol('Droste', [box]);

// a smaller, rotated instance of the SAME symbol + a frame become the new master
const inner = Y.placeInstance(sym, 130, 130);
Y.updateElement(inner, { width: 150, height: 150, angle: 0.12 });
const frame = Y.createRectangle(100, 100, 200, 200, { backgroundColor: 'transparent' });
Y.redefineSymbol(sym, [inner, frame]);

Y.symbolSelfReferences(sym);        // true
Y.setSymbolRecursive(sym, true, 40); // draw the nesting, at most 40 levels
Y.setSymbolRecursive(sym);           // omit the flag to toggle it back off

Asset library (reuse across documents)

Symbols live inside one document — an instance is a link to its master, so the two have to travel together in the same file. The Asset library is the other half of that story: a personal shelf of artwork that persists across every document you open in this browser. Draw a good tree, a rock, a cloud or a prop once, save it, and it is one click away in your next project.

Find it at the bottom of the Symbols panel. Select some artwork and press Save, give it a name, and it appears as a thumbnail. Click a thumbnail (or its +) to insert it into the current document, centred in your viewport. Double-click a name to rename; 🗑 removes it from the shelf.

The library is stored in this browser profile (IndexedDB), alongside your saved drawings. Like the drawings gallery it is convenience storage rather than a backup — export a .yappy file for anything you can’t afford to lose, and note that a different browser or machine starts with an empty shelf.

const Y = window.Yappy;

// save the current selection to the shelf
const meta = await Y.saveToAssetLibrary('Pine tree');   // { id, name, width, height, … }

// later, in ANY document:
const assets = await Y.listAssets();                    // newest first
await Y.insertAsset(assets[0].id);                      // → plain editable elements

await Y.renameAsset(meta.id, 'Pine tree (tall)');
await Y.deleteAsset(meta.id);

Scripting (API)

Symbols are fully scriptable from the global window.Yappy object — build a master from ids, scatter instances, redefine the master, and break the link.

const Y = window.Yappy; Y.clear();

// build a master from two shapes, then place more instances
const a = Y.createCircle(100, 100, 90, 90, { backgroundColor: '#2563eb' });
const b = Y.createStar(118, 118, 54, 54, 5, { backgroundColor: '#facc15' });
const sym = Y.createSymbol('Badge', [a, b]);   // returns the symbol id
Y.placeInstance(sym, 260, 100);
Y.placeInstance(sym, 420, 100);

Y.listSymbols();                 // [{ id, name, width, height, instances }, …]

// redefine the master from a redrawn version, or detach a copy
Y.redefineSymbol(sym, [newId1, newId2]);   // every instance updates
Y.detachInstance();                        // detach the selected instance(s)