``` ### 2. Never set `position: relative` on custom node classes The `.flow-node` class sets `position: absolute`. Any custom class that sets `position: relative` will override it, causing nodes to stack in document flow instead of being absolutely positioned: ```css /* WRONG — breaks node positioning */ .my-custom-node { position: relative; background: #fff; } /* CORRECT — flow-node already has position: absolute */ .my-custom-node { background: #fff; } ``` If child elements need a positioning context, `.flow-node` itself is already `position: absolute` which serves as a positioned ancestor. ### 3. Alpine scope isolation on `x-data` elements Directives and expressions on the SAME element as `x-data` evaluate in THAT element's scope only. They do NOT see parent `x-data` scopes: ```html

``` ### 4. `toolSettings` must be a scope property, not config Drawing directives read `toolSettings` from `Alpine.$data(el)`, not from the config object: ```html

``` ### 5. Freehand paths use `fill`, not `stroke` The `flow-freehand-end` event produces a filled outline path via perfect-freehand. Render with `fill`, not `stroke`: ```html ``` ### 6. SVG annotations need overflow:visible Annotation SVGs render at flow coordinates from a 1x1 container: ```html ``` ### 7. Panel CSS class selector When checking if a click target is inside a panel, use `.flow-panel` class, not `[x-flow-panel]` attribute: ```js // WRONG — attribute selector doesn't match Alpine directive attributes target.closest('[x-flow-panel]') // CORRECT — the directive adds this CSS class target.closest('.flow-panel') ``` ### 8. `viewportCulling` is opt-in Viewport culling is `false` by default. Enable it explicitly for performance on large diagrams: ```js flowCanvas({ viewportCulling: true, cullingBuffer: 100 }) ``` ### 9. `update()` vs `animate()` `update()` is the core method (instant by default). `animate()` is a wrapper with 300ms default: ```js // Instant update $flow.update({ nodes: { 'a': { position: { x: 300 } } } }); // Smooth transition (300ms default) $flow.animate({ nodes: { 'a': { position: { x: 300 } } } }); // Custom duration on either $flow.update({ nodes: { 'a': { position: { x: 300 } } } }, { duration: 500 }); ``` ## Common Patterns ### Minimal flow ```html

``` ### Whiteboard with all tools ```html

``` Event listeners needed for ALL tools: `flow-freehand-end`, `flow-highlight-end`, `flow-rectangle-draw`, `flow-arrow-draw`, `flow-circle-draw`, `flow-text-draw`. Each creates an annotation node with `class: 'flow-node-annotation'`. See whiteboard addon docs for complete event handler and node template code for every tool type. ### Timeline animation ```js $flow.timeline() .step({ nodes: ['a'], position: { x: 200 }, duration: 600, easing: 'easeInOut' }) .step({ nodes: ['b'], position: { x: 200 }, duration: 600 }) .parallel([ { edges: ['e1'], edgeColor: '#22c55e', duration: 400 }, { edges: ['e2'], edgeColor: '#22c55e', duration: 400 }, ]) .play() ``` ### Edge with draw-in animation ```js $flow.timeline() .step({ addEdges: [{ id: 'e-new', source: 'a', target: 'b', markerEnd: 'arrowclosed' }], edgeTransition: 'draw', duration: 800, }) .play() ``` ## Addon Registration Addons share a global registry via `globalThis.__alpineflow_registry__`. Core and addons can be loaded from different bundles: ```js import AlpineFlow from '@getartisanflow/alpineflow'; import AlpineFlowDagre from '@getartisanflow/alpineflow/dagre'; Alpine.plugin(AlpineFlow); Alpine.plugin(AlpineFlowDagre); // $flow.layout() now works — dagre registered on shared registry ``` ## Theming All visual properties use `--flow-*` CSS variables. Override on `.flow-container`: ```css .flow-container { --flow-node-selected-border-color: #3b82f6; --flow-node-hover-border-color: #3b82f6; --flow-handle-active-bg: #3b82f6; --flow-edge-stroke-selected: #3b82f6; } ``` Search docs for the full CSS variable reference — do not guess variable names. ## Key Defaults - `viewportCulling`: `false` (opt-in) - `fitViewOnInit`: `false` - `pannable`: `true` - `zoomable`: `true` - `minZoom`: `0.5`, `maxZoom`: `2` - `background`: `'dots'` - `connectOnClick`: `true` - `edgesReconnectable`: `true` - `history`: `false` (opt-in) - `selectionOnDrag`: `false` - `connectionMode`: `'strict'` Search docs for the complete configuration reference with 120+ options. --- > Source: [getartisanflow/alpineflow](https://github.com/getartisanflow/alpineflow) — distributed by [TomeVault](https://tomevault.io).