Configuration
Publishing the config
php artisan vendor:publish --tag=wireflow-config
This creates config/wireflow.php.
Options
inject_alpineflow
'inject_alpineflow' => true,
| Value | Behavior |
|---|---|
true (default) |
WireFlow expects AlpineFlow JS/CSS to be imported via Vite from the vendor path |
false |
Disables any auto-injection. Use this if you install @getartisanflow/alpineflow via npm and register it yourself. WireFlow Blade components still work. |
theme
'theme' => 'default',
| Value | CSS File | Description |
|---|---|---|
'default' |
alpineflow-theme.css |
Neutral zinc/slate theme with light and dark mode |
'flux' |
alpineflow-theme-flux.css |
Flux UI / Tailwind v4 native theme using --color-accent tokens |
'structural' |
— | Structural CSS only, no visual theme. Bring your own styles. |
'none' |
— | No CSS at all. You manage all imports manually. |
translations
'translations' => env('WIREFLOW_TRANSLATIONS', true),
| Value | Behavior |
|---|---|
true (default) |
Every <x-flow> passes the wireflow::canvas messages for app()->getLocale() and the locale itself to AlpineFlow, so built-in canvas text follows the app locale. See Translations. |
false |
Canvases stay in English unless you pass :translations or locale explicitly. The rendered canvas is identical to WireFlow before translations existed. |
Full config file
<?php
return [
/*
|--------------------------------------------------------------------------
| Auto-inject AlpineFlow
|--------------------------------------------------------------------------
|
| When true, WireFlow expects AlpineFlow JS/CSS to be imported via Vite
| from the vendor path. Set to false if you register AlpineFlow via npm
| yourself. WireFlow Blade components still work either way.
|
*/
'inject_alpineflow' => true,
/*
|--------------------------------------------------------------------------
| Theme
|--------------------------------------------------------------------------
|
| Which theme CSS to use: 'default' (zinc/slate), 'flux' (Tailwind v4 /
| Flux UI native), 'structural' (layout only, no visual styling), or
| 'none' (no CSS — you manage imports manually).
|
*/
'theme' => 'default',
/*
|--------------------------------------------------------------------------
| Translate Canvases
|--------------------------------------------------------------------------
|
| When enabled, every <x-flow> passes the 'wireflow::canvas' messages for
| the app locale and the locale itself to AlpineFlow. Set to false to
| leave canvases in English unless a :translations or locale prop is
| passed explicitly.
|
*/
'translations' => env('WIREFLOW_TRANSLATIONS', true),
];
Passing AlpineFlow config
The <x-flow> component promotes the most common options to named props. For everything else, use the config prop:
<x-flow
:nodes="$nodes"
:edges="$edges"
:config="[
'connectionSnapRadius' => 30,
'helperLines' => true,
'preventOverlap' => 10,
'selectionTool' => 'lasso',
]"
>
The config array is merged last, overriding any prop-derived values.
Common config options
These are the most frequently used options you can pass via the config prop. All have sensible defaults — you only set what you need to change.
Connections:
| Key | Type | Default | Description |
|---|---|---|---|
isValidConnection |
callback |
— | Custom validator: WireFlow::js('(conn) => conn.source !== conn.target'). Return false to reject. |
connectOnClick |
bool |
true |
Click source handle, then click target handle to connect. |
connectionSnapRadius |
int |
20 |
Pixel radius for snapping to nearby handles. 0 disables. |
connectionMode |
string |
'strict' |
'strict' = source→target only. 'loose' = any handle to any handle. |
multiConnect |
bool |
false |
Drag from one handle creates connections from ALL selected nodes. |
easyConnect |
bool |
false |
Hold Alt and drag from node body to connect. |
proximityConnect |
bool |
false |
Auto-create edges when dragging nodes near each other. |
Node behavior:
| Key | Type | Default | Description |
|---|---|---|---|
snapToGrid |
array|false |
false |
Snap to grid: [20, 20] for 20px grid. |
helperLines |
bool|array |
false |
Show alignment guides during drag. true for defaults. |
preventOverlap |
bool|int |
false |
Prevent nodes from overlapping. Pass number for gap in px. |
nodeExtent |
array |
— | Position boundaries: [[-500, -500], [500, 500]]. |
nodeDragThreshold |
int |
0 |
Minimum px distance before drag starts. |
elevateNodesOnSelect |
bool |
true |
Selected nodes render above others. |
reconnectOnDelete |
bool |
false |
Auto-bridge connections when deleting middle nodes. |
Selection:
| Key | Type | Default | Description |
|---|---|---|---|
selectionMode |
string |
'partial' |
'partial' = any overlap. 'full' = entire node inside box. |
selectionOnDrag |
bool |
false |
Selection box on plain drag (pair with 'panOnDrag' => [2]). |
selectionTool |
string |
'box' |
'box' or 'lasso'. |
Viewport:
| Key | Type | Default | Description |
|---|---|---|---|
panOnScroll |
bool |
false |
Scroll to pan instead of zoom. Ctrl+scroll zooms. |
translateExtent |
array |
— | Pan boundaries: [[-1000, -1000], [1000, 1000]]. |
viewportCulling |
bool |
true |
Only render visible nodes (performance). |
zoomOnDoubleClick |
bool |
true |
Double-click to zoom in. |
autoPanOnNodeDrag |
bool |
true |
Auto-pan when dragging near canvas edge. |
Drop zone:
| Key | Type | Default | Description |
|---|---|---|---|
onDrop |
callback |
— | Handle drops from external drag sources. Return a node array to add it. |
onEdgeDrop |
callback |
— | Handle connection drops on empty canvas. Return a node to auto-create. |
For the complete list of 120+ options, see the AlpineFlow configuration reference.
Runtime config updates
From the server, use the WithWireFlow trait to patch config at runtime:
$this->flowPatchConfig([
'pannable' => false,
'zoomable' => false,
]);
See WithWireFlow Trait for details.
Translations
Canvases follow your app's locale with no setup. <x-flow> passes the wireflow::canvas messages for app()->getLocale() to AlpineFlow together with the locale, so the built-in canvas text (control tooltips, loading text, accessible names and screen reader announcements) renders in the user's language. WireFlow ships English and German. For a locale without a catalog, Laravel falls back to your app.fallback_locale.
The workflow components (<x-flow-run-button>, <x-flow-stop-button>, <x-flow-reset-button>, <x-flow-replay-controls> and <x-flow-execution-log>) translate their default text through wireflow::components with __().
Turning it off
WIREFLOW_TRANSLATIONS=false
Or set 'translations' => false in config/wireflow.php. Canvases then stay in English unless you pass :translations or locale yourself. The flag only controls what <x-flow> passes to AlpineFlow. The workflow components always go through __(), and in an English app their text is the same as before.
Overriding messages
Publish the language files:
php artisan vendor:publish --tag=wireflow-lang
This copies canvas.php and components.php for each shipped locale to lang/vendor/wireflow/{locale}/. Laravel merges your files over WireFlow's key by key, so keep only the keys you change and delete the rest. You then keep receiving new and corrected messages when you upgrade.
// lang/vendor/wireflow/de/canvas.php
return [
'controls.zoomIn' => 'Näher heran',
];
To add a language WireFlow doesn't ship, create lang/vendor/wireflow/{locale}/canvas.php (and components.php if you use the workflow components) with the keys you need. Missing canvas keys fall back to English in the browser; missing component keys fall back to app.fallback_locale.
Keys are flat dotted strings in both files, in the same style as AlpineFlow (controls.zoomIn, runButton.idle). WireFlow's lang/en/canvas.php lists every engine message, and the AlpineFlow docs describe what each key prefix covers.
Regional locales
Laravel looks up the app locale exactly, then falls back to app.fallback_locale, never to the base language. An app on fr_CA therefore gets English canvas text even when WireFlow ships fr, and an app on de_AT doesn't pick up the German files. To fall back to the base language, add it to Laravel's locale chain in a service provider:
// AppServiceProvider::boot()
app('translator')->determineLocalesUsing(fn (array $locales) => collect($locales)
->flatMap(fn (string $locale) => [$locale, explode('_', $locale)[0]])
->all());
This applies to every translation in the app, not only WireFlow's. <x-flow> still passes the app locale (de_AT) to AlpineFlow, so plural forms follow the regional rules.
Per-canvas translations and locale
Pass :translations and locale to one canvas:
<x-flow
:nodes="$nodes"
:edges="$edges"
:translations="['controls.zoomIn' => 'Näher heran']"
locale="de"
/>
An explicit :translations replaces the app-locale catalog for that canvas, and keys you leave out fall back to English. To change one key and keep the rest of the locale's messages, spread the catalog first: :translations="[...trans('wireflow::canvas'), 'controls.zoomIn' => 'Näher heran']". Both props work even when wireflow.translations is off.
The config passthrough wins over both props: :config="['locale' => 'de-CH']".
The locale is passed as Laravel spells it (pt_BR). AlpineFlow normalises it to a BCP 47 tag (pt-BR) to pick plural forms.
Switching locale in a Livewire session
Messages are resolved once, when the canvas is created, and aren't reactive. <x-flow> also carries wire:ignore by default, so a locale change during a Livewire request doesn't reach a canvas that is already on the page. Key the canvas by locale so Livewire replaces it:
<x-flow wire:key="flow-{{ app()->getLocale() }}" :nodes="$nodes" :edges="$edges" />
Plurals
Engine messages that carry a :count exist once per CLDR plural category: announce.nodesSelected_one and announce.nodesSelected_other, plus _zero, _two, _few or _many for languages that need them. AlpineFlow picks the form in the browser with Intl.PluralRules for the canvas locale. Don't use Laravel's | plural syntax in these files. trans_choice() doesn't apply to them.
Contributing a language
- Engine messages (
canvas.php) are generated from AlpineFlow'slocales/*.jsonwhen WireFlow resyncs its bundled engine. Don't edit them in WireFlow; add or fix the language in AlpineFlow instead (see Adding a language). The next WireFlow release picks it up. - WireFlow component text (
components.php) lives in this repository. Copylang/en/components.phptolang/{locale}/components.phpand translate the values. A test checks that every key exists in English and keeps English's placeholders.
Related
- Installation — importing CSS and JS
- x-flow component — full props reference
- AlpineFlow Configuration — full config reference
- AlpineFlow Translations — message keys, plural forms,
$flow.t()