DiagramOptions

Shared configuration options accepted by every diagram-generation function.

Extended by

Properties

backgroundColor?

optional backgroundColor?: string;

Defined in: src/types/index.ts:450

Background color for PNG export

Default

'transparent'

catchHandling?

optional catchHandling?: CatchHandling;

Defined in: src/types/index.ts:458

How to treat per-state Catch (error-handler) branches. ‘show’ (default) renders them; ‘hide’ drops error edges and handler-only nodes so the happy path reads clearly on large machines.

Default

'show'

catchLabelStyle?

optional catchLabelStyle?: CatchLabelStyle;

Defined in: src/types/index.ts:464

Style for Catch block edge labels: ‘error-type’ shows error names, ‘catch-number’ shows “Catch #N”

Default

'error-type'

collapse?

optional collapse?: boolean | string[];

Defined in: src/types/index.ts:474

Collapse Parallel/Map containers into a placeholder node so dagre lays out a smaller graph — hiding a container’s children shrinks the diagram instead of leaving an empty bounding box behind. true collapses every container; a string array collapses only the named containers (names that don’t resolve to an existing container are ignored).

Default

undefined (no collapsing)

collapseControls?

optional collapseControls?: boolean;

Defined in: src/types/index.ts:486

Draw a collapse control in every open container’s header and an expand control on every collapsed placeholder, each tagged data-sfn-collapse-target="<id>", for the interactive viewer’s per-container collapse.

Only useful for interactive output — generateHtml sets it for itself when it embeds the in-browser relayout. It stays off by default so static SVG and PNG export carry no controls.

Default

false

customColors?

optional customColors?: Partial<Record<StateType, NodeStyle>>;

Defined in: src/types/index.ts:489

Custom styling overrides for specific state types

diagramDescription?

optional diagramDescription?: string;

Defined in: src/types/index.ts:495

Accessible description for the diagram, rendered as the root <svg>’s <desc>. Falls back to a state/transition count summary when omitted.

diagramTitle?

optional diagramTitle?: string;

Defined in: src/types/index.ts:503

Accessible name for the diagram, rendered as the root <svg>’s <title> and aria-label. generateSvg defaults it from the ASL definition’s top-level Comment when omitted.

Default

'AWS Step Functions state machine diagram'

edgeHitAreas?

optional edgeHitAreas?: boolean;

Defined in: src/types/index.ts:514

Render an invisible, thicker hit area beneath every edge so pointer events land on a comfortable target rather than on the drawn stroke, which is 1.5–2px wide.

Only useful for interactive output — generateHtml and the sfn-diagram/element custom element set it themselves so edges are clickable in the viewer. It stays off by default so static SVG and PNG export carry no extra paths.

Default

false

edgeOverrides?

optional edgeOverrides?: Record<string, EdgeStyleOverride>;

Defined in: src/types/index.ts:653

Per-edge style overrides. Merged on top of the edge’s computed style — only specified fields are overridden. Used by the execution overlay to highlight taken transitions and dim untaken ones.

Two key shapes are accepted:

GraphEdge.id — ${from}->${to}#${type}#${ordinal}, e.g. Route->Work#choice#1. Targets exactly one edge. Prefer this.
${from}->${to} — legacy, broad-matches every edge between that pair. Kept for backwards compatibility through 1.x; removal is deferred to 2.0.

When both match an edge, the qualified key is merged on top of the bare one.

Example

{
    'Route->Work': { strokeWidth: 2 },            // both branches
    'Route->Work#choice#1': { stroke: '#d13212' }, // only the second rule
}

edgeStyle?

optional edgeStyle?: EdgePathStyle;

Defined in: src/types/index.ts:520

Style of edge paths: straight, curved, or orthogonal

Default

'curved'

format?

optional format?: DiagramFormat;

Defined in: src/types/index.ts:523

Output format for the diagram

height?

optional height?: number;

Defined in: src/types/index.ts:526

Overall diagram height in pixels (auto-calculated if not specified)

iconPosition?

optional iconPosition?: "left" | "top" | "right";

Defined in: src/types/index.ts:532

Position of AWS service icons relative to node label

Default

'left'

iconResolver?

optional iconResolver?: (service) => string | null;

Defined in: src/types/index.ts:535

Custom function to resolve icon URLs for services

Parameters

service

string

Returns

string | null

iconSize?

optional iconSize?: number;

Defined in: src/types/index.ts:541

Size of AWS service icons in pixels

Default

includeComments?

optional includeComments?: boolean;

Defined in: src/types/index.ts:547

Whether to use state comments as node labels

Default

true

layout?

optional layout?: LayoutDirection;

Defined in: src/types/index.ts:550

Graph layout direction: TB (top-bottom), LR (left-right), RL (right-left), BT (bottom-top)

nodeAnnotations?

optional nodeAnnotations?: Record<string, string>;

Defined in: src/types/index.ts:660

Extra annotation text rendered below a node’s label, keyed by graph node id - the state name for every state whose name is unique across the machine. For a nested state whose name repeats elsewhere in the machine the id is qualified by its scope, so read it off the rendered data-state-id rather than assuming the bare name. Used by the execution overlay to show per-state duration and retry counts.

nodeHeight?

optional nodeHeight?: number;

Defined in: src/types/index.ts:556

Height of each state node in pixels

Default

nodeOverrides?

optional nodeOverrides?: Record<string, Partial<NodeStyle>>;

Defined in: src/types/index.ts:630

Per-node style overrides keyed by graph node id, which is the state name for every state whose name is unique across the machine. For a nested state whose name repeats elsewhere in the machine the id is qualified by its scope, so read it off the rendered data-state-id rather than assuming the bare name. Merged on top of the node’s computed style — only specified fields are overridden.

nodeSeparation?

optional nodeSeparation?: number;

Defined in: src/types/index.ts:562

Horizontal separation between nodes in pixels

Default

nodeWidth?

optional nodeWidth?: number;

Defined in: src/types/index.ts:568

Width of each state node in pixels

Default

padding?

optional padding?: number;

Defined in: src/types/index.ts:574

Padding around the diagram in pixels

Default

pngQuality?

optional pngQuality?: number;

Defined in: src/types/index.ts:585

PNG export quality from 1-100.

Has no effect on the default resvg engine (PNG is lossless, and resvg exposes no compression knob) or on the html-to-image fallback engine (its quality option is JPEG-only). Retained for backward compatibility. Use PngExportOptions.scale to control output resolution instead.

Default

rankSeparation?

optional rankSeparation?: number;

Defined in: src/types/index.ts:591

Vertical separation between ranks in pixels

Default

showIcons?

optional showIcons?: boolean;

Defined in: src/types/index.ts:597

Whether to display AWS service icons on Task state nodes

Default

false

showStateTypes?

optional showStateTypes?: boolean;

Defined in: src/types/index.ts:603

Whether to display state type labels on nodes

Default

false

showVariables?

optional showVariables?: boolean;

Defined in: src/types/index.ts:611

Whether to annotate nodes with the variables they assign via ASL Assign. Shown as $var1, $var2 beneath the node label. States that assign nothing are unaffected.

Default

true

stylePreset?

optional stylePreset?: StylePreset;

Defined in: src/types/index.ts:617

Visual style preset: ‘aws-standard’ uses rectangles (AWS parity), ‘enhanced’ uses shapes for visual distinction

Default

'aws-standard'

theme?

optional theme?: ThemeOption;

Defined in: src/types/index.ts:620

Color theme: ‘light’, ‘dark’, or custom theme object

width?

optional width?: number;

Defined in: src/types/index.ts:623

Overall diagram width in pixels (auto-calculated if not specified)