npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

ionodes

v0.1.6

Published

A reusable React node graph editor for generic graph data.

Readme

ionodes

A reusable, domain-neutral node graph editor for React, TypeScript, and @xyflow/react. It provides editable nodes and connectors, validation, undo and redo, compact nodes with optional click-to-expand editors, and a versioned JSON format. The editor ships with a customizable theme and a small interactive demo.

Source code · Changelog · License

Quick start

npm install ionodes @xyflow/react react react-dom
import { GraphEditor, createGraph } from 'ionodes';
import 'ionodes/style.css';

export function App() {
  return <GraphEditor defaultGraph={createGraph('example')} />;
}

The demo is available in the repository with npm install followed by npm run dev.

Customize the editor

The editor is designed to be themed by the consuming React app. theme applies inline CSS properties and --ionodes-* custom properties to this editor instance, so separate editors can use separate themes. Built-in tokens are --ionodes-bg, --ionodes-panel, --ionodes-panel-raised, --ionodes-border, --ionodes-text, --ionodes-muted, --ionodes-subtle, --ionodes-accent, --ionodes-accent-strong, --ionodes-danger, --ionodes-success, --ionodes-font-sans, --ionodes-font-mono, --ionodes-panel-padding, --ionodes-control-height, --ionodes-focus-ring, and --ionodes-radius.

import { GraphEditor, createGraph, type GraphEditorTheme } from 'ionodes';

const theme = {
  '--ionodes-bg': '#f4f6fa',
  '--ionodes-panel': '#ffffff',
  '--ionodes-panel-raised': '#edf1f7',
  '--ionodes-border': '#cbd3df',
  '--ionodes-text': '#202938',
  '--ionodes-muted': '#586579',
  '--ionodes-subtle': '#778397',
  '--ionodes-accent': '#6750d8',
  '--ionodes-accent-strong': '#4f39ba',
  '--ionodes-focus-ring': '#6750d8',
  '--ionodes-radius': '12px'
} satisfies GraphEditorTheme;

<GraphEditor defaultGraph={createGraph('example')} theme={theme} className="brand-graph" />;

className is placed on the editor root. Use it to override detailed surface styles, including node bodies, headers, connector rows and handles, connections, inspector fields, canvas controls, and the background. Selectors are namespaced with .ionodes-*; React Flow selectors such as .react-flow__edge-path can be used for wires and controls.

.brand-graph .ionodes-node {
  background: #fff;
  border: 1px solid #cbd3df;
  box-shadow: 0 8px 24px #23304a18;
}

.brand-graph .ionodes-node-header {
  background: #edf1f7;
}
.brand-graph .ionodes-connector-label {
  color: #344054;
}
.brand-graph .react-flow__edge-path {
  stroke-width: 3;
}

The canvas prop configures or replaces the React Flow background, controls, and minimap. The background can be supplied as a React element; controls and minimap can be hidden or replaced. Grid spacing/color, minimap colors, and default connection/validation colors are configurable. nodeTypes and getNodeType replace built-in node markup entirely. renderNodeActions places consumer-provided actions at the right side of each built-in node header. selectedNodeId selects a node programmatically; omit it to keep node selection internal to the editor. renderNodeEditor adds an optional click-to-expand editor inside each built-in node; node editors start collapsed and their open/closed state is transient. nodeEditorLabel changes the accessible toggle label. renderConnectorLabel customizes connector content while retaining graph handles; renderGraphIcon maps graph icon descriptor names to React elements. The icons prop replaces built-in UI symbols, and each palette entry can provide its own icon element. Connector and connection color values remain in graph data.

<GraphEditor
  defaultGraph={graph}
  theme={theme}
  canvas={{
    backgroundColor: '#d6deeb',
    backgroundGap: 28,
    backgroundSize: 1.5,
    connectionColor: '#6750d8',
    invalidConnectionColor: '#c03952',
    showMiniMap: false
  }}
  icons={{ undo: <UndoIcon />, redo: <RedoIcon />, 'palette-add': <PlusIcon /> }}
  renderGraphIcon={(name) => <MyIcon name={name} />}
/>

The icons keys are node, validation, palette-add, undo, redo, delete, connector-add, connector-remove, export, import, close, selection-node, selection-connection, empty-graph, data-export, data-import, dismiss, error, input-add, output-add, connection, selection-empty, input-direction, output-direction, and fit-shortcut. Omitted entries keep the default symbol. The customization types are exported from the package entry point.

Validation and error messages

Validation feedback and editor errors can be hidden independently. Hiding validation feedback does not disable validation or allow an invalid connection:

<GraphEditor defaultGraph={graph} showValidationMessages={false} showErrorMessages={false} />

Use renderMessage to replace message content with text or any React element. Validation messages include the full GraphIssue (including its message and affected elementId); error messages include the original error text. Return null to suppress one message while leaving the other messages visible:

import { GraphEditor, type EditorMessage } from 'ionodes';

function renderMessage(message: EditorMessage) {
  if (message.kind === 'validation') {
    return <strong>Connection issue: {message.issue.message}</strong>;
  }
  return <span role="alert">Could not complete action: {message.message}</span>;
}

<GraphEditor defaultGraph={graph} renderMessage={renderMessage} />;

Style the built-in message containers with className and the exported messageClassNames hooks. The default classes are .ionodes-validation and .ionodes-toast:

<GraphEditor
  defaultGraph={graph}
  className="brand-graph"
  messageClassNames={{ validation: 'brand-validation', error: 'brand-error' }}
/>
.brand-graph .brand-validation {
  color: #7c2d12;
  background: #ffedd5;
  border: 1px solid #fdba74;
  border-radius: 8px;
}

.brand-graph .brand-error {
  color: #7f1d1d;
  background: #fee2e2;
  border: 1px solid #fca5a5;
  border-radius: 8px;
}

These controls cover validation feedback and errors displayed by the editor, such as import/export and connection errors. Errors from graph helper functions called directly by the consuming app should be caught and displayed by that app.

API

GraphEditor accepts graph for controlled state or defaultGraph for internal state. Use onChange to receive graph edits. palette supplies React-friendly node creation actions. validateConnection can reject a proposed connection with a boolean or an explanatory message. Optional panels can be hidden with showPalette and showInspector. renderNodeEditor can place configuration beside the node's connector rows without expanding the node's canvas footprint; it receives the current GraphNode and the same update callback as custom node renderers. The editor UI state is not serialized. showValidationMessages, showErrorMessages, renderMessage, and messageClassNames control feedback visibility, content, and styling. onSelectionChange and onGraphEvent expose editor events. Pass selectedNodeId to select a node programmatically; null clears the selected node while preserving any selected connection. theme, canvas, icons, and rendering hooks customize the appearance without changing the persisted graph format.

The library exports graph types and immutable helpers including createGraph, addNode, removeNode, upsertConnector, removeConnector, addConnection, removeConnection, validateGraph, serializeGraph, and deserializeGraph. See API and custom nodes for the full TypeScript API and extension example.

Documentation

Development

Scripts: npm run dev, npm run build, npm run build:lib, npm run build:demo, npm test, npm run lint, npm run typecheck, and npm run format:check.

License

Apache-2.0. See LICENSE.