@flowskin-bpmn/flowskin-bpmn
v1.1.0
Published
A modern skin layer for BPMN diagrams — themed nodes, animated edges, and hover cards built on bpmn-js
Maintainers
Readme
FlowSkin BPMN
A modern, themeable BPMN renderer built on bpmn-js. Replaces the standard BPMN notation with a clean, futuristic design language while keeping full BPMN 2.0 XML compatibility underneath.
Features
- Custom node designs for all BPMN element types (tasks, events, gateways, data, artifacts)
- Distinct SVG icons per element type (service task, user task, script task, etc.)
- Dark/light theme with automatic color adaptation for inline BPMN colors
- Node state badges (running, completed, incident, hold) with visual indicators
- Edge animations (parallel dots, sequential traversal, loading beads)
- Edge highlighting API for process visualization
- Hover cards showing element metadata
- Default flow markers, boundary event indicators, call activity double borders
- Association/data flow differentiation from sequence flows
- Zero-config — works out of the box with any BPMN 2.0 XML
Installation
npm install flowskin-bpmnPeer dependency
npm install bpmn-jsQuick Start
import { createFlowSkinBPMN } from 'flowskin-bpmn';
import 'flowskin-bpmn/styles';
const renderer = createFlowSkinBPMN({
container: '#canvas',
theme: 'dark',
hoverCard: true,
});
await renderer.loadXml(bpmnXmlString);API
createFlowSkinBPMN(options)
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| container | string \| HTMLElement | required | CSS selector or DOM element |
| theme | 'dark' \| 'light' | 'dark' | Initial color theme |
| hoverCard | boolean | true | Show details card on hover (toggle later with setHoverCard) |
Returns a renderer instance with these methods:
Instance Methods
// Load/render BPMN XML
await renderer.loadXml(xmlString);
// Theme
renderer.setTheme('light');
renderer.getTheme(); // 'light' | 'dark'
// Animate edges by ID
const stop = renderer.animateEdges(['Flow_1', 'Flow_2'], {
type: 'loading', // 'parallel' | 'sequential' | 'loading'
color: '#00e5ff', // optional override
speed: 1.5, // optional multiplier
});
stop(); // remove animation
// Highlight edges
const unhighlight = renderer.highlightEdge('Flow_1', {
color: '#ff6b6b',
width: 4,
glow: true,
});
unhighlight();
// Highlight multiple
const unhighlightAll = renderer.highlightEdges(['Flow_1', 'Flow_2'], {
color: '#22c55e',
});
unhighlightAll();
// Stop all animations
renderer.stopAllEdgeAnimations();
// Node state badges
renderer.setNodeStates({
'Task_1': 'running', // green spinner badge
'Task_2': 'completed', // gray checkmark badge
'Task_3': 'incident', // red ⚡ badge + pulsating glow
'Task_4': 'hold', // yellow pause badge
});
// Clear specific badges
renderer.clearNodeStates(['Task_1', 'Task_2']);
// Clear all badges
renderer.clearNodeStates();
// Hover details card — switch on/off at any time
renderer.setHoverCard(false); // off
renderer.setHoverCard(true); // on
renderer.toggleHoverCard(); // flip, returns the new state
renderer.isHoverCardEnabled(); // -> boolean
// Access underlying bpmn-js viewer
const viewer = renderer.getViewer();
// Cleanup
renderer.destroy();Node State Badges
Visualize runtime process state by applying badges to any node. Badges appear outside the top-right corner of the node.
| State | Badge | Effect |
|-------|-------|--------|
| running | Green circle with spinning loader | Indicates active execution |
| completed | Gray circle with ✓ checkmark | Node finished successfully |
| incident | Red circle with ⚡ bolt | Pulsating red glow on the node |
| hold | Yellow circle with ⏸ pause bars | Execution paused/waiting |
renderer.setNodeStates({
'ServiceTask_1': 'running',
'UserTask_2': 'completed',
'ScriptTask_3': 'incident',
'CallActivity_4': 'hold',
});Node Designs
Tasks
| Type | Icon | Style |
|------|------|-------|
| Service Task | </> code brackets | Card with icon + label |
| User Task | Person silhouette | Card with icon + label |
| Send Task | Paper plane | Card with icon + label |
| Receive Task | Inbox tray | Card with icon + label |
| Script Task | Terminal console | Card with icon + label |
| Business Rule Task | Decision table | Card with icon + label |
| Manual Task | Checkmark | Card with icon + label |
| Call Activity | External link | Double-border card |
Events
| Type | Icon | |------|------| | Timer | Clock face | | Error | Lightning bolt | | Message | Envelope | | Signal | Triangle | | Terminate | Red stop | | Conditional | List lines | | Escalation | Upward arrow | | Compensate | Rewind | | Cancel | X cross | | Link | Arrow pentagon |
Event indicators:
- Start events: thin green inner circle
- End events: bold dark border
- Boundary/catch events: dashed purple inner ring
Gateways
| Type | Icon | |------|------| | Exclusive | Diamond with branches | | Parallel | Fork split | | Inclusive | Circle with branches | | Complex | Asterisk | | Event-based | Pentagon in circle |
Other Elements
| Type | Design | |------|--------| | Participant (Pool) | Header band + building icon | | Lane | Dashed border | | Sub-process | Dashed container + layers icon | | Data Store | Database cylinder | | Data Object | Document with fold | | Text Annotation | Open bracket + italic text | | Group | Dashed rounded rectangle |
Edges
| Type | Design | |------|--------| | Sequence Flow | Solid line + start dot + end bar | | Default Flow | Chevron marker near source | | Association | Dotted thin line | | Data Association | Dotted + arrowhead |
Themes
Colors automatically adapt between light and dark modes. Inline BPMN colors (bioc:fill, bioc:stroke) are also adapted — light fills become muted in dark mode, dark strokes lighten subtly.
renderer.setTheme('dark'); // Muted backgrounds, bright accents
renderer.setTheme('light'); // White backgrounds, standard colorsRunning the Demo
git clone <repo-url>
cd flowskin-bpmn
npm install
npm run devOpens http://localhost:3000 with a sample BPMN diagram. Use the toolbar to:
- Import your own
.bpmnfile - Toggle animation modes
- Switch between custom and raw BPMN rendering
- Toggle dark/light theme
Project Structure
lib/ # The library (published to npm)
index.js # Public API
theme.js # Theme + color adaptation
utils.js # Shared utilities
hoverCard.js # Hover overlay
styles.css # Base styles (import in your app)
badges.js # Node state badges API
renderer/
BeatRenderer.js # bpmn-js BaseRenderer
shapes.js # Node draw functions
edges.js # Edge draw + highlight
icons.js # Icon imports + type mapping
animations/
index.js # animateEdges API
icons/ # 28 SVG icons
demo/ # Demo application
index.html
main.js
styles.css
sample.bpmnLicense
MIT
