VueCraft NPM

Configuration ​

One object configures everything: VisualLinkerConfig. It is grouped by what it styles, so a setting is always in the place you would look for it. The same object is accepted by createVisualLinker(), by the config prop of <VisualLinker>, by useVisualLinker(), and by the visualLinker key of the Nuxt module.

ts
const linker = createVisualLinker(el, {
  theme: darkTheme,
  lines: {
    curve: 'smoothstep',
    color: '#6fcf97',
    width: 2,
    hover: { width: 3 },
    bezier: { curvature: 0.5 },
    smoothstep: { cornerRadius: 8 },
    routing: { avoidObstacles: true, padding: 12 },
    jumps: { radius: 6 },
    animated: { shape: 'dots', speed: 50 },
  },
  markers: { end: { shape: 'arrow', hover: { size: 10 } }, sizes: { arrow: 8 } },
  ports: { show: true, radius: 4, hover: { radius: 6 }, spread: { gap: 16 } },
  labels: { background: '#fff', fontSize: 11 },
  blocks: { draggable: true, drag: { grid: 20, bounds: 'container' } },
  interaction: { hover: true, highlight: true, selectable: true, clipToScrollParents: 'pin' },
})

Every field is optional. A field left out falls through to the built-in value, so an empty config {} is a valid, complete configuration.

Where a value comes from ​

For any visual setting the first of these that has a value wins:

  1. The field on the entity itself — a connection's style, a port, a block, a label.
  2. The matching group of the configuration passed to the engine.
  3. The shared configuration of the Vue app or Nuxt project, when there is one (see Shared Configuration).
  4. The theme token.
  5. A CSS variable that your own stylesheet defines.
  6. The built-in value.

Configurations from several layers are merged field by field, state by state, not replaced as a whole: setting lines.hover.width in one place and lines.hover.color in another gives a hover state with both.

A connection's style has the same shape as the lines group, plus markers: { start, end }. Whatever can be set for every line can be set for a single one, in the same words.

Lines ​

The group lines sets the default look and routing of every connection. Its fields:

  • curve — 'bezier' | 'straight' | 'smoothstep' · default: 'bezier'. See Connections.
  • color — string · default: '#2e8b57', or the theme's line.
  • width — number · default: 1.5.
  • dashed — boolean · default: false.
  • opacity — number, 0..1 · default: 1.
  • highlight, hover, selected, focus — the same fields, applied in that state. See Visual States.
  • animated — boolean | ConnectionFlow · default: off. See Animated Flow.
  • bezier — { curvature, minReach, maxReach, angleBlend, angleMaxOffset } · the shape of bezier curves, see below.
  • smoothstep — { cornerRadius, maxTrunkReach } · the shape of smoothstep lines, see below.
  • routing — { avoidObstacles, padding } · see Routing and Crossings.
  • jumps — boolean | { radius } · default: off. See Routing and Crossings.

The bezier group, for curve: 'bezier' only:

  • curvature — number · default: 0.5. Control-point reach as a fraction of the distance between the endpoints, before the min/max clamp.
  • minReach — number · default: 24. Floor on control-point reach, in px, whatever the distance.
  • maxReach — number · default: 160. Ceiling on control-point reach, in px — the main knob for how bowed a long connection gets.
  • angleBlend — number, 0..1 · default: 0.55. How far the exit and entry angle leans toward the other endpoint instead of staying perpendicular to the border; 0 turns the lean off.
  • angleMaxOffset — number, degrees · default: 30. Absolute ceiling on that lean.

The smoothstep group, for curve: 'smoothstep' only:

  • cornerRadius — number · default: 8. Radius of the rounded 90° bends, branch points included.
  • maxTrunkReach — number · default: 48. Only for connections that share a port and a side: caps how far their common trunk extends before splitting. Siblings that disagree use the smallest value.

The group routing, for smoothstep only:

  • avoidObstacles — boolean · default: false.
  • padding — number · default: 12. Clearance kept from every other block, in px.

Markers ​

The group markers sets the markers at the ends of every connection and the default size of each built-in shape.

  • start, end — false | MarkerShape | MarkerConfig · default: unset, which shows the built-in port dot. A shape name is shorthand for { shape }; false removes even the dot, leaving a bare point. A marker configured here replaces the dot at that end of every connection. The marker fields and their states are described in Connection Styling.
  • sizes — { circle, square, diamond, arrow } · default: 6 for each. The size of a marker of that shape that sets no size of its own, as a multiple of the line's current stroke width.

Ports ​

The group ports sets the built-in dot drawn at every resolved port, and the defaults for ports.

  • show — boolean · default: true. Draws the dot. The #port slot and the layout event work either way.
  • radius — number · default: 4.
  • fill — string · default: '#ffffff', or the theme's portFill.
  • stroke — string · default: follows the line color, or the theme's portStroke.
  • strokeWidth — number · default: 1.5.
  • opacity — number, 0..1 · default: 1.
  • highlight, hover, selected, focus — the same fields, in that state of the dot's connection.
  • side — 'auto' | FixedSide | FixedSide[] · default: 'auto'. The side for every port that sets none of its own.
  • offset — number, 0..1 · default: 0.5. The position along that side for every port that sets none of its own.
  • spread — boolean | { gap, padding } · default: off. See Port Spreading.

Labels ​

The group labels sets the look of every label the library draws itself — those with a text. See Connection Labels.

  • background — string · default: '#ffffff', or the theme's labelBackground.
  • border — string · default: follows the line color, or the theme's labelBorder.
  • color — string · default: '#1c1e2b', or the theme's labelText.
  • fontSize — number, px · default: 11.
  • paddingX, paddingY — number, px · default: 6 and 3.
  • opacity — number, 0..1 · default: 1.
  • highlight, hover, selected, focus — the same fields, in that state of the label's connection.

Blocks ​

The group blocks sets how blocks can be dragged. See Drag & drop.

  • draggable — boolean · default: false. A block's own draggable overrides it.
  • drag — { grid, bounds }.
    • grid — number, px · default: unset, free movement. Dragged blocks snap their page position to this grid.
    • bounds — 'container' | HTMLElement | DragBoundsInset · default: unset, unconstrained. A block's own dragBounds overrides it.

Interaction ​

The group interaction switches on behavior that goes beyond drawing.

  • hover — boolean · default: false. The pointer over a line puts it into the hover state and shows a pointer cursor. See Visual States.
  • highlight — boolean · default: false. The pointer over a block puts its connections into the highlight state. See Visual States.
  • selectable — boolean · default: false. See Selection & Accessibility.
  • clipToScrollParents — boolean | 'pin' | 'hide' · default: 'pin'. See Scrolling Containers.

Theme ​

The field theme holds the color tokens — one place for the colors of lines, ports and labels, written to CSS variables. See Themes.

Strings and enums ​

Fixed choices — a curve type, a marker shape, a port side, a marker's orientation — are written as plain strings:

ts
lines: { curve: 'smoothstep' },
markers: { end: { shape: 'arrow', orient: 'fixed' } },

A port's side takes the same strings ('left', 'right', 'top', 'bottom', 'auto'). The package also exports an enum for each choice — VLConnectionCurveEnum, VLMarkerShapeEnum, VLFixedSideEnum and VLOrientEnum — and a member such as VLMarkerShapeEnum.ARROW is accepted wherever its string is, with the same value. Use whichever you prefer: the strings need no import, the enums give you autocompletion by name.

Changing the configuration at runtime ​

The engine takes a new configuration at any time, and everything is redrawn:

ts
linker.setConfig({ lines: { color: '#e0526c' } }) // merged into the current one
linker.setConfig({ lines: { color: undefined } }) // undefined removes a key
linker.replaceConfig(nextConfig) // replaces everything
const current = linker.getConfig() // a copy of what is in effect
  • setConfig(patch) deep-merges the patch into the current configuration. A key set to undefined is removed, so a setting can be unset again.
  • replaceConfig(next) replaces the whole configuration.
  • getConfig() returns a copy; changing it does not change the engine.

Settings that attach listeners follow along: turning blocks.draggable on or off makes blocks draggable or not, and turning interaction.selectable off clears the selection and makes the lines plain graphics again. In Vue, change the config prop or a ref instead — see VisualLinker Component.