@eventcatalog/visualizer

React components for visualizing EventCatalog nodes, built for ReactFlow.

Installation

npm install @eventcatalog/visualizer
# or
pnpm add @eventcatalog/visualizer

Setup

1. Import the CSS (Required)

The components use Tailwind CSS classes. Import the CSS file in your main CSS file:

/* In your main CSS file (e.g., globals.css, index.css) */
@import '@eventcatalog/visualizer/dist/styles.css';

2. Configure Tailwind (Required for proper styling)

The visualizer components use Tailwind CSS classes. You must configure your build system to include these classes:

For Tailwind CSS v4 (PostCSS):

Add the visualizer package to your postcss.config.js:

export default {
  plugins: {
    "@tailwindcss/postcss": {
      content: [
        // ... your existing paths
        './node_modules/@eventcatalog/visualizer/dist/**/*.{js,mjs}',
        './node_modules/@eventcatalog/visualizer/src/**/*.{js,ts,jsx,tsx}',
      ],
    },
  },
};

For Tailwind CSS v3 (Config file):

Add the visualizer package to your content paths in tailwind.config.js:

module.exports = {
  content: [
    // ... your existing paths
    './node_modules/@eventcatalog/visualizer/dist/**/*.{js,mjs}',
    './node_modules/@eventcatalog/visualizer/src/**/*.{js,ts,jsx,tsx}',
  ],
  // ... rest of config
}

⚠️ Important: Without this configuration, the Tailwind classes used by the visualizer components will be purged from your CSS build, resulting in unstyled components.

Usage

Basic EventNode

import { EventNode } from '@eventcatalog/visualizer';

// Use as standalone component
<EventNode
  id="event-1"
  data={{
    name: "User Registered",
    version: "1.0.0",
    summary: "Fired when a user registers for the first time",
    mode: "full",
    owners: ["team-auth", "team-users"],
    sends: ["user-profile-updated"],
    receives: ["user-registration-request"]
  }}
  selected={false}
/>

Standalone Usage

The EventNode is a pure visual component that can be used anywhere:

import { EventNode } from '@eventcatalog/visualizer';

<EventNode
  id="event-1"
  data={{
    name: "User Registered",
    version: "1.0.0",
    summary: "Fired when a user registers for the first time",
    mode: "full",
  }}
  selected={false}
/>

With ReactFlow

For ReactFlow integration, wrap the EventNode with ReactFlow handles:

import { ReactFlow, Handle, Position } from '@xyflow/react';
import { EventNode } from '@eventcatalog/visualizer';

// Create a ReactFlow node wrapper
function ReactFlowEventNode(props) {
  const { id, data, selected } = props;
  return (
    <>
      <Handle type="target" position={Position.Left} />
      <Handle type="source" position={Position.Right} />
      <EventNode id={id} data={data} selected={selected} />
    </>
  );
}

const nodeTypes = {
  event: ReactFlowEventNode,
};

const nodes = [
  {
    id: '1',
    type: 'event',
    position: { x: 100, y: 100 },
    data: {
      name: 'User Registered',
      version: '1.0.0',
      summary: 'Fired when a user registers',
      mode: 'full',
    },
  },
];

export default function MyFlow() {
  return (
    <ReactFlow
      nodes={nodes}
      nodeTypes={nodeTypes}
    />
  );
}

Node Configuration

The visualizer also exports node configurations:

import { eventConfig } from '@eventcatalog/visualizer';

// Access node metadata
console.log(eventConfig.type); // 'event'
console.log(eventConfig.color); // 'orange'
console.log(eventConfig.icon); // Zap component

Props

EventNodeProps

| Prop | Type | Default | Description | |------|------|---------|-------------| | id | string | required | Node ID | | data | EventNodeData | required | Node data | | selected | boolean | false | Whether node is selected |

EventNodeData

| Property | Type | Description | |----------|------|-------------| | name | string | Event name | | version | string | Event version | | summary | string | Event description | | mode | 'simple' \| 'full' | Display mode | | owners | string[] | Event owners | | sends | string[] | Messages this event sends | | receives | string[] | Messages this event receives |

Styling

Components are styled with Tailwind CSS classes. The package includes:

• Tailwind Classes: All standard Tailwind utilities used in components
• Custom CSS: Minimal custom styles exported in dist/styles.css
• Responsive: Components work across different screen sizes
• Themeable: Easy to customize with Tailwind's theming system

Features

• ✅ Pure Visual Component: Clean separation between visual and ReactFlow concerns
• ✅ Standalone Usage: Works perfectly outside ReactFlow contexts
• ✅ TypeScript: Full TypeScript support with proper types
• ✅ Self-Contained Styling: Complete CSS bundle with all required Tailwind classes
• ✅ Configurable: Support for simple and full display modes
• ✅ Framework Agnostic: Can be wrapped for any flow library (ReactFlow, etc.)
• ✅ Zero Dependencies: No ReactFlow dependency, just pure React component