Format reference

A .flux.json file is validated against the JSON Schema. Add it at the top of your file to get autocomplete and inline errors in your editor:

{ "$schema": "https://fluxygram.app/schema/v1.json", "type": "flow", "nodes": [] }

The tables below are generated from that schema, so they always match what Fluxygram accepts.

Diagram

Field	Type or values	Description
type required	flow · architecture · timeline · tree · cycle · sequence · mindmap	Diagram type. Each one has its own default motion.
title	string	Shown above the diagram. Say what it shows.
theme	dark · light
direction	LR · TB	Layout direction for flow diagrams.
nodes required	node[]
edges	edge[]
groups	group[]	Layers for architecture diagrams, listed top to bottom.
steps	step[]	Optional story. Steps are cumulative. Without steps, the type's default motion is used.
finale	boolean	After the last step the camera zooms out and every visible connection flows at once. Set false to end on the last step.
motion	object	Default animation for the whole diagram. Blocks and connections can override enter / travel.

Nodes (blocks)

Field	Type or values	Description
id required	id
label required	string	Short name, ideally 1 to 3 words.
description	string	One short line under the name.
icon	175 names	Built-in icon name.
kind	default · decision · start · end · data · database · note	Block shape. decision: diamond (phrase it as a question). start/end: pill. data: parallelogram (input/output). database: cylinder. note: folded note for annotations.
group	id	architecture only: the layer this node belongs to.
date	string	timeline only, for example "1995" or "2026-03".
accent	boolean	Highlight this node with the accent color.
x	number	Manually pinned position (top-left), set by the visual editor. Omit it to let Fluxygram place the node.
y	number	Manually pinned position (top-left). Use together with x.
enter	fade · scale · draw · slide	How a block enters. fade: fades up (default). scale: grows with a slight bounce. draw: its outline is traced, then fill and text appear. slide: slides in.
state	success · error · warning · pending · default	State from the start (steps can change it). success: green + check. error: red, shakes. warning: amber, badge blinks. pending: in progress, dashed border spins.

id is unique across nodes, connections and groups: letters, digits, - and _. See every icon in the icon list.

Edges (connections)

Field	Type or values	Description
id	id	Needed to reference the edge from steps. Defaults to "from->to".
from required	id
to required	id
label	string
carries	string	What travels along the edge. Shown next to the particle ("token", "$", "event"). 1 or 2 words.
travel	particle · pulse · dash · packets	What travels along a connection when it flows. particle: comet dot (default). pulse: a stretch of light. dash: dashes marching continuously. packets: small spaced blocks.
state	success · error · warning · pending · default	State from the start. Colors the line, the particle and the label (e.g. a path that fails).

A connection without id gets "from->to" as its id.

Groups

Field	Type or values	Description
id required	id
label required	string

Steps

Field	Type or values	Description
show	id[]	Elements that appear. Showing an edge also shows its two nodes.
hide	id[]
focus	id	The camera moves in on this node or group.
flow	id	Edges a particle travels along while the step is active.
highlight	id	Elements that stand out; the rest dims.
caption	string	Text for the step. Keep it under 12 words.
state	object	Changes node or connection states from this step on: { "pay": "success", "e3": "error" }. "default" clears it.
duration	number (0.5–60)	Seconds this step stays on screen during autoplay (overrides motion.hold).
notes	string	Speaker notes for this step. Shown only in the presenter view (/present), never in the diagram.

Motion

Field	Type or values	Description
enter	fade · scale · draw · slide	How a block enters. fade: fades up (default). scale: grows with a slight bounce. draw: its outline is traced, then fill and text appear. slide: slides in.
travel	particle · pulse · dash · packets	What travels along a connection when it flows. particle: comet dot (default). pulse: a stretch of light. dash: dashes marching continuously. packets: small spaced blocks.
speed	slow · normal · fast
camera	follow · fixed	follow: the camera follows the action. fixed: everything always in view.
finale	boolean
hold	number (0.5–60)	Seconds each step stays on screen during autoplay. Omit it to let Fluxygram time each step by its content.

Errors

Fluxygram validates every file and explains problems in plain language, in English or Spanish, with the path to the field:

edges[2].to: "to" points to "x", which is not a node.
steps[1].flow: "e9" is not the id of any node, edge or group.

The same validation is available in code through @fluxygram/core.