Canvas Configuration

Core options that control the canvas appearance and viewport behavior.

INTERACTIVE
<div x-data="flowCanvas({
    nodes: [
        { id: 'a', position: { x: 0, y: 0 }, data: { label: 'Node A' } },
        { id: 'b', position: { x: 250, y: 0 }, data: { label: 'Node B' } },
        { id: 'c', position: { x: 125, y: 100 }, data: { label: 'Node C' } },
    ],
    edges: [
        { id: 'e1', source: 'a', target: 'b' },
        { id: 'e2', source: 'a', target: 'c' },
    ],
    background: 'cross',
    backgroundGap: 30,
    fitViewOnInit: true,
    minZoom: 0.5,
    maxZoom: 3,
    controls: false,
    pannable: false,
    zoomable: false,
})" class="flow-container" style="height: 250px;">
    <div x-flow-viewport>
        <template x-for="node in nodes" :key="node.id">
            <div x-flow-node="node">
                <div x-flow-handle:target></div>
                <span x-text="node.data.label"></span>
                <div x-flow-handle:source></div>
            </div>
        </template>
    </div>
</div>

Options

Option Type Default Description
pannable boolean true Enable viewport panning.
zoomable boolean true Enable viewport zooming.
interactive boolean true Master interactivity switch. Set false to start the canvas locked (no pan, zoom, or drag) without a post-ready toggleInteractive() call. It overrides the per-axis pannable/zoomable at init (both forced off); toggleInteractive() (or the controls toggle) then restores the per-axis intent. Distinct from the per-node locked flag, which freezes a single node.
containerHeight 'auto' | 'fill' | number | string 'auto' Canvas container height. 'auto' = the 400px fallback, 'fill' = 100% of the parent, a number = pixels, or any CSS length string ('80vh'). Overrides the --flow-container-height CSS variable.
minZoom number 0.5 Minimum zoom level.
maxZoom number 2 Maximum zoom level.
fitViewOnInit boolean false Auto-fit all nodes in view after initialization.
background string | BackgroundLayer[] 'dots' Background pattern: 'dots', 'lines', 'cross', 'none', or array of layers.
backgroundGap number 20 Grid spacing in pixels. Overrides --flow-bg-pattern-gap.
patternColor string — Pattern color. Overrides --flow-bg-pattern-color. Supports rgba().
ariaLabel string canvas.label message ARIA label for the container.
translations FlowTranslations — Partial message overrides; missing keys fall back to English. See Translations.
locale string <html lang>, then 'en' Locale for plural forms in translations. Laravel-style pt_BR is accepted.
colorMode 'light' | 'dark' | 'system' — Color mode management. 'system' tracks OS preference. Adds/removes .dark class.
debug boolean false Enable debug logging to console.

Translations

Pass a partial translations dictionary to flowCanvas. Each canvas manages its own messages, omitted keys retain their English defaults. No extra translation library is required.

import de from '@getartisanflow/alpineflow/locales/de.json';

Alpine.data('germanDiagram', () => ({
    config: {
        controls: true,
        locale: 'de',
        translations: { ...de, 'controls.zoomIn': 'Näher heran' },
    },
}));
<div x-data="germanDiagram">
    <div x-data="flowCanvas(config)" class="flow-container"></div>
</div>

Without a bundler, importing JSON in the browser needs an import attribute: import de from '/vendor/alpineflow/locales/de.json' with { type: 'json' };.

The FlowTranslations interface lists every key with a short description of where it appears; locales/en.json holds the English defaults. The JSON dictionaries in locales/ are the single source for engine messages; the build copies them to dist/locales/ for npm and downstream PHP consumers.

Keys are flat dotted strings grouped by where the message appears:

Prefix Covers
controls.* Controls panel buttons and its ARIA label.
canvas.* Container label, loading text, selection-mode indicator.
a11y.* Accessible names of nodes, edges, handles and the control-point hint.
announce.* Screen reader announcements.
workflow.* Default labels of workflow nodes.
schema.inspector.* Schema inspector UI.

Developer diagnostics and condition expressions remain technical text.

Messages are plain text. Keep placeholders such as :label, :source, :target and :count in your translations; values are substituted literally without interpreting HTML. Empty strings and non-string values (as some translation export tools write them) are ignored and fall back to English.

Every canvas exposes its resolved messages as t(key, values), so custom templates and toolbars can reuse them via $flow:

<button @click="$flow.zoomIn()" :title="$flow.t('controls.zoomIn')">+</button>
<span x-text="$flow.t('announce.nodesSelected', { count: $flow.selectedNodes.size })"></span>

Messages that carry a :count exist once per CLDR plural category, suffixed _zero, _one, _two, _few, _many or _other (i18next's convention), for example announce.nodesSelected_one / announce.nodesSelected_other. The form is picked with Intl.PluralRules for the canvas locale, so French treats 0 as singular and Polish uses _few / _many. Provide the categories your language needs; _other is used when a category is missing, and English fallbacks always follow English plural rules. A specific form such as _one or _two may spell the number out instead of using :count; _other must keep :count. For grammar beyond plurals, use the existing announcements.formatMessage callback; it receives the canvas translator as third argument, so it can delegate unhandled events to the default formatter without losing translations.

locale defaults to document.documentElement.lang, which Laravel layouts set from app()->getLocale(). Underscores are normalised (pt_BR → pt-BR) and an invalid tag falls back to en.

Explicit ariaLabel, loadingText, node labels and custom announcement formatters keep precedence. Messages are resolved once when the canvas is created and are not reactive; recreate the canvas to change its language.

See also