Raphaël: JavaScript Vector Graphics Library

2.3.0 · abandoned · verified Sun Apr 19

Raphaël is a JavaScript library designed to simplify working with vector graphics on the web. It uses SVG for modern browsers (Firefox, Safari, Chrome, Opera) and VML for older Internet Explorer, providing a consistent API across different rendering engines. The current stable version is 2.3.0, released in 2018. The library is largely considered feature-complete but is no longer actively maintained, with the last code changes dating back several years. Key differentiators include its cross-browser compatibility, especially its VML fallback for legacy IE, and its relatively small footprint. Development is dormant, with releases historically occurring sporadically as PRs were gathered and tested. It relies on the `eve` library for custom event handling.

Common errors

```
Raphael is not defined
```
cause The Raphaël library script was not loaded or executed before being accessed, or it's being used in an environment where the global `Raphael` variable is not available (e.g., an ES Module context without proper bridging).

fix Ensure `<script src="path/to/raphael.js"></script>` is placed before any code attempting to use `Raphael`. For bundled environments, use `const Raphael = require('raphael');` and ensure your bundler processes it correctly.
```
Uncaught ReferenceError: eve is not defined
```
cause This error typically occurs when using `raphael.no-deps.js` (or `.min.js`) without explicitly loading the `eve` library beforehand.

fix Load `eve.js` from `https://cdnjs.cloudflare.com/ajax/libs/eve/0.4.2/eve.min.js` (or a similar source) before loading `raphael.no-deps.js`. Alternatively, use the standard `raphael.js` (or `.min.js`) distribution, which includes `eve`.
```
TypeError: paper.path is not a function
```
cause This usually indicates that `paper` is not a valid Raphaël canvas object, or it was not initialized correctly, perhaps due to a DOM element not existing when `Raphael()` was called.

fix Ensure the target DOM element for the Raphaël canvas exists and is accessible when `Raphael(element, width, height)` is called. Wrap your Raphaël initialization code in a `window.onload` or `DOMContentLoaded` event listener if executed from the `<head>`.

Warnings

breaking The `R.ninja` method, previously used for certain internal operations, will now throw a strict error if called directly. This indicates an internal change that might affect highly customized implementations.
Fix: Avoid direct calls to `R.ninja`. Review usage if migrating from older versions; this method was not part of the public API.
gotcha Raphaël is largely unmaintained. While functional, it may encounter compatibility issues with very new browser versions or modern JavaScript features. Security updates are highly unlikely.
Fix: For new projects, consider actively maintained alternatives like SVG.js, Paper.js, or Snap.svg. For existing projects, thoroughly test across target browsers and use polyfills if necessary.
gotcha The default build (`raphael.js`, `raphael.min.js`) includes the `eve` dependency. If using `raphael.no-deps.js` or `raphael.no-deps.min.js`, `eve` must be provided separately, or core functionality (like event handling) will fail.
Fix: Ensure `eve` is loaded *before* `raphael.no-deps.js` when using the no-deps distribution, typically via a separate script tag or an AMD/CommonJS module loader.
deprecated The original project website, `raphaeljs.com`, is no longer active. The official documentation and project information can now be found on the GitHub Pages site.
Fix: Update any bookmarks or references to `https://dmitrybaranovskiy.github.io/raphael/` for the current project page.

Install

npm install raphael npm
yarn add raphael yarn
pnpm add raphael pnpm

Imports

Raphael
wrong:
```
import Raphael from 'raphael';
```
correct:
```
<script src="path/to/raphael.js"></script>
// Then Raphael is available globally
```
Raphaël is primarily a global-first library. While UMD compliant, it's not designed for modern ES Modules. For bundled environments, use `require` or rely on the global.
Raphael (CommonJS)
wrong:
```
import * as Raphael from 'raphael';
```
correct:
```
const Raphael = require('raphael');
```
This imports the version that includes 'eve'. For a 'no-deps' version, use `require('raphael/raphael.no-deps')` and manage 'eve' separately.
Raphael (AMD)
wrong:
```
require(['raphael'], function(R) {});
```
correct:
```
define([ "path/to/raphael" ], function(Raphael) {
  // Use Raphael here
});
```
The README suggests `define` for AMD usage, passing the resolved module as an argument to the callback function. The `raphael.amd.js` file is the main entry point for AMD and Browserify since v2.2.0.

Quickstart

This quickstart demonstrates how to initialize a Raphaël canvas, draw basic shapes like circles and rectangles, and add text to the canvas using a simple HTML file with a CDN import.

<html>
<head>
  <title>Raphaël Quickstart</title>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/raphael/2.3.0/raphael.min.js"></script>
</head>
<body>
  <div id="holder"></div>
  <script>
    window.onload = function () {
      // Create a canvas with a width of 320px and a height of 200px
      // and place it in the element with the ID 'holder'.
      var paper = Raphael(document.getElementById('holder'), 320, 200);

      // Draw a circle at x=50, y=50 with a radius of 40
      var circle = paper.circle(50, 50, 40);
      circle.attr({
        fill: '#f00',
        stroke: '#fff',
        'stroke-width': 5
      });

      // Draw a rectangle at x=100, y=20 with width=100, height=60
      var rect = paper.rect(100, 20, 100, 60);
      rect.attr({
        fill: '#0f0',
        stroke: '#000',
        'stroke-width': 2,
        opacity: 0.7
      });

      // Add text
      var text = paper.text(250, 100, "Hello Raphaël");
      text.attr({
        font: '20px Arial',
        fill: '#00f'
      });
    };
  </script>
</body>
</html>

view raw JSON →