Patchbay.js

JavaScript library for creating interactive physics-based rope simulations connected to DOM elements.

Inspired by Reason Studio's Rack (Video).

Installation

Using npm

npm install patchbay.js

# Or with yarn
yarn add patchbay.js

Using a CDN

<script src="https://unpkg.com/patchbay.js/dist/patchbay.umd.js" defer></script>

Configuration Options

Option	Type	Default	Description
color	string	"#000000"	The color of the cable.
dragHandleSize	number	25	The size of the drag handles in pixels.
gravity	number	1	The gravity factor applied to the cable. Higher values make the cable sag more.
iterations	number	5	The number of iterations to solve constraints. Higher values increase stability but may impact performance.
lineThickness	number	2	The thickness of the cable line in pixels.
segments	number	20	The number of segments in the cable. More segments allow for smoother curves but may impact performance.
slack	number	1.1	The slack factor of the cable. Values greater than 1 allow the cable to hang loosely.
snapRadius	number	100	The radius (in pixels) for snapping to connector elements when dragging cable ends.
snapTargetSelector	string	".cable-connector"	The CSS selector for identifying snap target elements.
draggable	boolean	true	Whether the cable start/end points are draggable by the user.

Usage Example

import { Patchbay } from "patchbay.js";

const patchbay = new Patchbay({
  // Global configuration for all cables
  color: "#FF0000",
  gravity: 1.5,
  segments: 30,
  draggable: true,
});

patchbay.connect(document.getElementById("input-1"), document.getElementById("output-2"), {
  // Specific configuration for this cable, overriding global settings
  color: "#00FF00",
  slack: 1.2,
  snapRadius: 150,
});

patchbay.start();

Snapping to HTML Elements when Dragging

Patchbay.js supports snapping to HTML elements when dragging cable ends. To enable this feature, set the snapTargetSelector option to a valid CSS selector for the elements you want to snap to. Patchbay.js will automatically snap the cable end points to the nearest element when dragging.

Snap here
<div id="start" class="cable-connector"></div>

and here initially.
<div id="end" class="cable-connector"></div>

And if you drag the cable ends close to these elements, it will snap to them.
<div id="snap-here-on-drag" class="cable-connector"></div>

<script>
  const patchbay = new Patchbay({
    // Selector to snap elements to when releasing the cable ends after dragging
    snapTargetSelector: ".cable-connector",
  });

  const start = document.getElementById("start");
  const end = document.getElementById("end");
  patchbay.connect(start, end);
  patchbay.start();
</script>

Examples

Check out the examples directory for some examples of how to use Patchbay.js.

• Basic Example - A simple example demonstrating the basic usage of Patchbay.js.
• Snapping Example - An example demonstrating how to snap cable ends to HTML elements.
• Customization Example - An example demonstrating how to customize the appearance and behavior of cables.
• Using the CDN - An example showing how to use Patchbay.js with a CDN.
• Click to add - An example demonstrating how to add cables by clicking on elements.

Development

To set up the development environment:

1. Clone the repository
2. Run npm install to install dependencies
3. Run npm run build to build the library for production

git clone [email protected]:HelgeSverre/patchbay-js.git
cd patchbay-js
npm install
npm run build

Formatting

This project uses Prettier for code formatting. To format the code, run:

npm run format

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is MIT licensed.