Skip to content
Get packs

Guide · Open source

How to use Raphaël: install, load and draw vector graphics

Updated · written with AI from the project's own documentation and checked against our catalogue data

Raphaël is an open-source JavaScript library for drawing shapes, lines and other vector graphics in a web page using code. It is aimed at developers who want browser-based vector drawings, such as custom charts or diagrams, without a plugin. After this guide you will know what Raphaël is suited for, how to build it from source, how to load it into a page and where its limits are.

RaphaëlDmitryBaranovskiy/raphael · ★ 11.3k · MIT

Quick start

  1. 1Check prerequisites. Make sure NPM and Yarn are installed on your machine, since the build needs NPM.
  2. 2Clone the repository. Run git clone on the official DmitryBaranovskiy/raphael GitHub repository.
  3. 3Install dependencies. Inside the cloned folder, run yarn install --frozen-lockfile.
  4. 4Build the files. Run yarn build-all to produce all distributable files.
  5. 5Pick a distributable. Choose raphael.min.js for a minified build with eve included, or a no-deps file if you load eve separately.
  6. 6Load it in your page. Add the file with a script tag, or load it with AMD, then call Raphaël from your own code.

What Raphaël is and who it suits

Raphaël is a code library, not a finished chart product. It lets web pages draw shapes, lines and other vector graphics, such as charts or diagrams, using JavaScript. It aims to work consistently across different web browsers.

It is a good fit for developers adding custom drawings or simple charts to a website, front-end developers who want vector graphics without a plugin, and maintainers of projects that already use Raphaël. It is not a fit for people who need a ready-made chart product with no coding.

Install Raphaël by cloning and building from source

The README describes an install method based on cloning the repository and building it. You need NPM installed to build the library. The project also uses Yarn for installing dependencies.

Run the three commands below from the README in order: clone the repository, install dependencies with a frozen lockfile, then build all distributable files.

  • Prerequisites: NPM and Yarn
  • Clone the repository from the official GitHub URL
  • Install dependencies, then build all distributable files
git clone https://github.com/DmitryBaranovskiy/raphael.git yarn install --frozen-lockfile yarn build-all

Choose the right distributable file

All distributable files are UMD compliant. The README lists four options. The two files with eve included need no separate dependency. The no-deps files leave out eve, which the library depends on, so you must load eve yourself.

Minified files are smaller and suited to production. Non-minified files are easier to read and debug.

  • raphael.min.js: includes eve, minified
  • raphael.js: includes eve, not minified
  • raphael.no-deps.js: excludes eve, not minified
  • raphael.no-deps.min.js: excludes eve, minified

Load Raphaël into a page

Raphaël can be loaded with a script tag or with AMD. The README points to the Raphael-boilerplate project for examples of loading. The AMD example below shows how the module is received once the file path is set.

Once the script is loaded, your own code can create a drawing surface and add shapes to it.

  • Script tag: include the distributable file in your HTML page
  • AMD: pass the path to the file to define() and receive Raphael as a parameter
define([ "path/to/raphael" ], function( Raphael ) { console.log( Raphael ); });

Test and experiment with Raphaël

Testing is manual at present. The README says there is no automated way to run tests. To run them you run npx bower install and open dev/test/index.html in your browser.

To try things out, the README suggests the dev/raphaelTest.html file. You need to serve the root directory with a local server, and run npm run start before this works. An example server command given is python -m SimpleHTTPServer, run in the raphael directory, then visit http://localhost:8000/dev/raphaelTest.html.

  • Automated tests: none; testing is manual
  • Experiment file: dev/raphaelTest.html, served from a local server
npx bower install python -m SimpleHTTPServer

Know the limits before you commit

The README says that because many browsers are supported, accepting a pull request can take a while, and the maintainers also use feedback from other users. Versions are released as new PRs are gathered and tested.

If your project needs new features or fast fixes, plan for that delay. Projects that need automated tests should also note that the README describes testing as manual.

  • Pull request acceptance can be slow
  • Testing is manual
  • Not a no-code chart tool

What people use it for

  • Drawing custom diagrams inside a web page
  • Building simple charts for a website without a plugin
  • Maintaining an existing project that already uses Raphaël
  • Experimenting with vector shapes in dev/raphaelTest.html

Frequently asked questions

How do I install Raphaël?

The README describes cloning the repository from GitHub, then running yarn install --frozen-lockfile and yarn build-all. You need NPM installed to build the library.

Is Raphaël free to use?

Raphaël is licensed under the MIT license, as stated in the README. The copyright notices name Dmitry Baranovskiy and Sencha Labs.

What do I need to run Raphaël?

The source gives NPM and Yarn as prerequisites for building. The library is loaded into a web page as a script, and it depends on eve, which is included in some distributable files.

Which file should I load in my page?

Use raphael.min.js if you want a minified file with eve included. Use raphael.no-deps.min.js if you load eve yourself. The README says all distributable files are UMD compliant.

What are alternatives to Raphaël?

The project lists Snap.svg, D3.js, Paper.js and Fabric.js as comparable projects. Choose based on your needs, since the source does not rank them against each other.

Why are my tests not running automatically?

The README says there is no automated way to run tests right now. You must run npx bower install and open dev/test/index.html in your browser to test manually.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Raphaël suits developers who want to draw custom vector graphics or simple charts in the browser with code and an MIT-licensed library. It is a poor choice for anyone who wants a ready-made, no-code chart tool, or for projects that need quick fixes, new features or automated tests.

Install options & downloads