syncfusion-javascript-sankey

# Implementing Sankey Diagrams in Syncfusion TypeScript & JavaScript The Syncfusion EJ2 Sankey component visualizes quantitative flows and relationships between categories. Nodes represent sources, destinations, or intermediate stages, while links represent directed flows whose rendered thickness is determined by numeric values. This skill covers framework-neutral implementations for: - TypeScript applications using npm and module imports. - JavaScript applications using a versioned EJ2 CDN bundle. - Node and link configuration. - Tooltips and legends. - Node and link highlighting. - Sankey interaction events. - Horizontal and Vertical orientations. - Right-to-left rendering. - Themes and visual customization. - Exporting and printing when supported. - Accessibility configuration. - Responsive layouts. - Runtime data validation. - Performance optimization. - Dynamic data updates. ## Platform Support ### TypeScript Use TypeScript when the application uses: - The `@syncfusion/ej2-charts` npm package. - TypeScript compilation. - Webpack, Vite, or another module bundler. - Strongly typed Sankey models. - Explicit feature-module injection. - IDE IntelliSense and compile-time validation. Install the package: ```bash npm install @syncfusion/ej2-charts ``` Basic import: ```typescript import { Sankey, type SankeyLinkModel, type SankeyNodeModel } from '@syncfusion/ej2-charts'; ``` Import and inject optional modules when their features are enabled: ```typescript import { Sankey, SankeyLegend, SankeyTooltip } from '@syncfusion/ej2-charts'; Sankey.Inject( SankeyTooltip, SankeyLegend ); ``` ### JavaScript Use global JavaScript when the application uses: - A versioned CDN bundle. - A locally hosted EJ2 global bundle. - Traditional HTML and JavaScript files. - The global `ej` namespace. - No TypeScript compilation. The global Sankey constructor is: ```javascript ej.charts.Sankey ``` Global JavaScript loaded through the complete EJ2 bundle does not require explicit `Sankey.Inject(...)` calls. ### JavaScript Language Level The JavaScript examples use ES5-compatible syntax where practical: ```text var declarations Traditional functions No optional chaining No JavaScript module imports Global ej namespace ``` A modern browser is still recommended. ## When to Use This Skill Use this skill when the task requires: - Visualizing directed data flows. - Showing flow magnitude between categories. - Creating revenue-allocation diagrams. - Displaying energy generation and consumption. - Modeling material or inventory movement. - Visualizing conversion funnels. - Showing customer journeys. - Creating multi-stage process diagrams. - Configuring Sankey nodes and links. - Applying individual node or link colors. - Styling all nodes or links consistently. - Adding node and link tooltips. - Displaying a Sankey legend. - Handling node and link events. - Applying interaction highlighting. - Using Horizontal or Vertical orientation. - Supporting right-to-left layouts. - Creating responsive Sankey diagrams. - Exporting or printing a Sankey when supported. - Providing accessible descriptions and data alternatives. - Updating Sankey data dynamically. - Validating Sankey data before rendering. - Optimizing a complex Sankey visualization. ## Implementation Rules ### Rule 1: Provide Complete Examples A runnable TypeScript example should include: ```text Imports Required feature-module injection Node collection Link collection Sankey configuration HTML host element CSS dimensions appendTo call ``` A runnable JavaScript example should include: ```text Versioned EJ2 global script Node collection Link collection Sankey configuration HTML host element CSS dimensions appendTo call ``` ### Rule 2: Use Explicit DOM Attachment Preferred TypeScript: ```typescript const sankey: Sankey = new Sankey({ nodes, links }); sankey.appendTo( '#sankey-container' ); ``` Preferred JavaScript: ```javascript var sankey = new ej.charts.Sankey({ nodes: nodes, links: links }); sankey.appendTo( '#sankey-container' ); ``` Avoid passing the selector as the second constructor argument. ### Rule 3: Ensure the Host Exists Required HTML: ```html <div id="sankey-container"></div> ``` Required attachment: ```typescript sankey.appendTo( '#sankey-container' ); ``` The host ID and selector must match. ### Rule 4: Provide a Measurable Height Required CSS: ```css #sankey-container { width: 100%; min-height: 500px; } ``` Recommended component dimensions: ```typescript width: '100%', height: '500px' ``` Avoid: ```typescript height: 'auto' ``` If `height: '100%'` is used, every relevant ancestor must have a definite computed height. ### Rule 5: Inject Every Enabled TypeScript Feature Feature-module mapping: ```text Tooltip -> SankeyTooltip Legend -> SankeyLegend Export -> SankeyExport ``` Example: ```typescript import { Sankey, SankeyLegend, SankeyTooltip } from '@syncfusion/ej2-charts'; Sankey.Inject( SankeyTooltip, SankeyLegend ); ``` Do not inject unused modules. ### Rule 6: Keep Imports and Injection Synchronized Incorrect: ```typescript import { Sankey } from '@syncfusion/ej2-charts'; Sankey.Inject( SankeyTooltip ); ``` Correct: ```typescript import { Sankey, SankeyTooltip } from '@syncfusion/ej2-charts'; Sankey.Inject( SankeyTooltip ); ``` ### Rule 7: Do Not Inject Modules in Global JavaScript Avoid: ```javascript ej.charts.Sankey.Inject( ej.charts.SankeyTooltip, ej.charts.SankeyLegend ); ``` Use the global constructor directly: ```javascript var sankey = new ej.charts.Sankey({ tooltip: { enable: true }, legendSettings: { visible: true }, nodes: nodes, links: links }); sankey.appendTo( '#sankey-container' ); ``` ### Rule 8: Use Type-Only Model Imports Preferred: ```typescript import { Sankey, SankeyLegend, SankeyTooltip, type SankeyLinkModel, type SankeyNodeModel } from '@syncfusion/ej2-charts'; ``` This keeps runtime imports separate from TypeScript-only types. ### Rule 9: Configure the Title as a String Incorrect: ```typescript title: { text: 'Sales Flow Diagram' } ``` Correct: ```typescript title: 'Sales Flow Diagram' ``` The subtitle is also a separate string: ```typescript subTitle: 'Product revenue distribution' ``` ### Rule 10: Use the Node Label Model Incorrect: ```typescript { id: 'Product A', label: 'Product A' } ``` Correct: ```typescript { id: 'Product A', label: { text: 'Product A' } } ``` ### Rule 11: Keep Node IDs Unique Every node requires a unique, nonempty ID. ```typescript const nodes: SankeyNodeModel[] = [ { id: 'Product A' }, { id: 'Product B' }, { id: 'Revenue' } ]; ``` Avoid: ```typescript const nodes: SankeyNodeModel[] = [ { id: 'Revenue' }, { id: 'Revenue' } ]; ``` ### Rule 12: Match Link IDs to Existing Nodes Every `sourceId` and `targetId` must match an existing node `id`. ```typescript const links: SankeyLinkModel[] = [ { sourceId: 'Product A', targetId: 'Revenue', value: 100 } ]; ``` Identifiers are case-sensitive. ```text Product A product a PRODUCT A ``` These are different identifiers. ### Rule 13: Use Finite Positive Link Values Valid: ```typescript { sourceId: 'Product A', targetId: 'Revenue', value: 100 } ``` Avoid: ```text Numeric strings Zero Negative numbers NaN Infinity null undefined Missing values ``` ### Rule 14: Keep Node Styling at the Correct Level Individual node properties include: ```text id label color offset ``` Shared node styling belongs under `nodeStyle`: ```typescript nodeStyle: { width: 24, padding: 14, fill: '#2563eb', stroke: '#1e3a8a', strokeWidth: 1, opacity: 0.9, highlightOpacity: 1, inactiveOpacity: 0.25 } ``` Do not assign global node-style properties directly to individual nodes. ### Rule 15: Keep Link Styling at the Correct Level Individual link properties include: ```text sourceId targetId value color ``` Shared link styling belongs under `linkStyle`: ```typescript linkStyle: { opacity: 0.5, highlightOpacity: 1, inactiveOpacity: 0.2, curvature: 0.55, colorType: 'Blend' } ``` Do not assign global opacity or curvature directly to individual links. ### Rule 16: Use Supported Interaction Events Validated Sankey interaction and rendering events can include: ```text nodeEnter nodeLeave nodeClick linkEnter linkLeave linkClick nodeRendering linkRendering tooltipRendering legendItemRendering labelRendering load loaded sizeChanged ``` Do not use Cartesian Chart point events such as: ```text pointMouseMove pointClick pointRender selectionComplete ``` ### Rule 17: Use Highlighting Instead of Unsupported Selection Do not use: ```typescript selectionMode: 'Point' ``` Do not call: ```typescript sankey.select([ { id: 'Product A' } ]); ``` Use node and link interaction opacity: ```typescript nodeStyle: { opacity: 0.9, highlightOpacity: 1, inactiveOpacity: 0.25 }, linkStyle: { opacity: 0.5, highlightOpacity: 1, inactiveOpacity: 0.15 } ``` ### Rule 18: Use Supported Orientations Horizontal: ```typescript orientation: 'Horizontal' ``` Vertical: ```typescript orientation: 'Vertical' ``` Do not add an unsupported `nodeAlignment` property. ### Rule 19: Use `enableRtl` for RTL Rendering ```typescript enableRtl: true ``` Do not reverse source and target IDs merely to create an RTL presentation. ### Rule 20: Use Public Configuration Do not depend on undocumented internal selectors: ```css .e-sankey { border-radius: 8px; } ``` Use an application-owned wrapper: ```html <section class="sankey-card"> <div id="sankey-container"></div> </section> ``` ```css .sankey-card { border-radius: 8px; box-shadow: 0 2px 8px rgb(0 0 0 / 10%); } ``` ### Rule 21: Do Not Use Encoded or Editor-Generated Code Executable HTML must use actual tags. Correct: ```html <div id="sankey-container"></div> ``` Incorrect: ```html &lt;div id="sankey-container"&gt;&lt;/div&gt; ``` Do not place the following inside executable code: ```text <a> <strong> <br> data-lexical-text Editor-generated class names ``` ## Navigation Guide ### Getting Started and Setup Read: ```text references/getting-started.md ``` Use this reference for: - npm installation. - TypeScript imports. - JavaScript CDN setup. - Direct Sankey initialization. - Container creation. - Node and link data structure. - Module injection. - First Sankey diagram. - Initialization troubleshooting. ### Nodes Configuration Read: ```text references/nodes-configuration.md ``` Use this reference for: - `SankeyNodeModel`. - Node IDs. - Node labels. - Individual node colors. - Global `nodeStyle`. - Node borders. - Node width and padding. - Interaction opacity. - Node offsets. - Node positioning. - `nodeRendering`. - Data-driven node colors. - Node validation. ### Links Configuration Read: ```text references/links-configuration.md ``` Use this reference for: - `SankeyLinkModel`. - Source and target IDs. - Link values. - Individual link colors. - Global `linkStyle`. - Source, Target, and Blend colors. - Link opacity and curvature. - Balanced flow values. - Splitting and merging flows. - Multi-stage flows. - Link events. - `linkRendering`. - Dynamic data transformation. - Link validation. ### Customization and Appearance Read: ```text references/customization-and-appearance.md ``` Use this reference for: - Built-in themes. - Node and link colors. - Title and subtitle text. - Title and subtitle styles. - Label typography. - Horizontal and Vertical orientations. - Background colors and images. - Chart borders.