declarative-canvas

JavaScript/TypeScript library which lets you draw on HTML5 Canvas in a declarative way.

Installation

npm install declarative-canvas

Example Usage

The following code draws a rectangle and a circle on a canvas.

import { createDrawFunction, objectTypes } from 'declarative-canvas';

const canvas = document.getElementById('canvas');
const context = canvas.getContext('2d');

const objectsToRender = [
  { type: objectTypes.RECT, x: 50, y: 100, width: 200, height: 100 },
  { type: objectTypes.CIRCLE, x: 200, y: 100, radius: 100 },
];

const draw = createDrawFunction();

draw({ context, objects: objectsToRender });

Storybook

More examples can be found in the storybook. Source code of storybook stories is placed in the src/stories directory.

API Reference

declarative-canvas exports four objects/functions:

• createDrawFunction - draw function factory,
• objectTypes - dictionary object of available object types which can be drawn,
• drawMethods - dictionary object of available drawing methods.
• convertCanvasCoordinates - lets you convert canvas coordinates to base coordinates that you use to render objects.

createDrawFunction

A factory function that takes one optional argument:

(customDrawHandlers = {}) => Function

customDrawHandlers argument is described in Custom draw handlers chapter.

A function returned from this factory has the following signature:

({
  context: CanvasRenderingContext2D,
  objects: Array<object>,
  canvasWidth = context.canvas && context.canvas.width,
  canvasHeight = context.canvas && context.canvas.width,
  camera = { position: { x: canvasWidth / 2, y: canvasHeight / 2 }, zoom: 1 },
}) => void

objectTypes

{
  CIRCLE: 'CIRCLE',
  PATH: 'PATH',
  IMAGE: 'IMAGE',
  TEXT: 'TEXT',
  RECT: 'RECT',
  TRANSFORM: 'TRANSFORM',
}

drawMethods

{
  FILL: 'FILL',
  STROKE: 'STROKE',
  FILL_AND_STROKE: 'FILL_AND_STROKE',
}

Draw method tells the renderer if the given graphical object should be drawn by filling it with some color or just by drawing its outline (or both).

convertCanvasCoordinates

(
  x: number,
  y: number,
  canvasWidth: number,
  canvasHeight: number,
  camera: Camera
) => { x: number, y: number }

A function that converts canvas coordinates (for example event.offsetX and event.offsetY from onclick event) to base coordinates that you use to render objects (taking into account any transformations caused by camera's position and zoom).

Available graphical objects

Rectangle

{
  type: objectTypes.RECT;
  contextProps?: Partial<CanvasRenderingContext2D>;
  drawMethod?: string;
  x: number;
  y: number;
  width: number;
  height: number;
  rotation?: number;
}

contextProps - Canvas context props. Default: {}
drawMethod - Draw method. Default: drawMethods.FILL
x - position of the center of rectangle in X axis
y - position of the center of rectangle in Y axis
width - rectangle width
height - rectangle height
rotation - rectangle rotation in radians. Default: 0

Circle

{
  type: objectTypes.CIRCLE;
  contextProps?: Partial<CanvasRenderingContext2D>;
  drawMethod?: string;
  x: number;
  y: number;
  radius: number;
}

contextProps - Canvas context props. Default: {}
drawMethod - Draw method. Default: drawMethods.FILL
x - position of the center of circle in X axis
y - position of the center of circle in Y axis
radius - circle radius

Path

{
  type: objectTypes.PATH;
  contextProps?: Partial<CanvasRenderingContext2D>;
  drawMethod?: string;
  points: Array<{ x: number; y: number }>,
  closePath?: boolean,
}

contextProps - Canvas context props. Default: {}
drawMethod - Draw method. Default: drawMethods.FILL
points - array of points that make the path
closePath - indicates if the last point should be connected to the first point. Default: false

Image

{
  type: objectTypes.IMAGE;
  contextProps?: Partial<CanvasRenderingContext2D>;
  image
  x: number;
  y: number;
  width?: number;
  height?: number;
  rotation?: number;
}

contextProps - Canvas context props. Default: {}
image - Image object
x - position of the center of image in X axis
y - position of the center of image in Y axis
width - image width. Defaults to image orginal width
height - image height. Defaults to image orginal height
rotation - image rotation in radians. Default: 0

Text

{
  type: objectTypes.TEXT;
  contextProps?: Partial<CanvasRenderingContext2D>;
  drawMethod?: string;
  text: string;
  x: number;
  y: number;
}

contextProps - Canvas context props. Default: {}
drawMethod - Draw method. Default: drawMethods.FILL
image - Image object
text - text to be rendered
x - position of the text in X axis. Text horizontal and vertical align can be adjusted by contextProps
y - position of the text in Y axis Text horizontal and vertical align can be adjusted by contextProps

Transform

{
  type: objectTypes.TRANSFORM;
  contextProps?: Partial<CanvasRenderingContext2D>;
  children: Array<GraphicalObject>;
  dx?: number;
  dy?: number;
  scaleX?: number;
  scaleY?: number;
  skewX?: number;
  skewY?: number;
  rotation?: number;
}

contextProps - Canvas context props. Default: {}
children - array of graphical objects
dx - displacement of child objects in X axis. Default: 0
dy - displacement of child objects in Y axis. Default: 0
scaleX - scaling of child objects in X axis. Default: 1
scaleY - scaling of child objects in Y axis. Default: 1
skewX - skew transformation applied to child objects in X axis. Default: 0
skewY - skew transformation applied to child objects in Y axis. Default: 0
rotation - rotation in radians of child objects. Default: 0

Context Props

For every graphical object you can specify contextProps property. Before drawing graphical object, all values of contextProps object will be assigned to Canvas Rendering Context. Some example values that you can use: fillStyle, strokeStyle, lineWidth, filter and so on. After drawing the graphical object, context properties will be restored back to their orginal values.

Custom draw handlers

If you want to expand the capabilities of declarative-canvas to support more object types, you can specify custom draw handlers which will be used to draw objects with specified object type. Draw handler is a function with the following signature:

(context, options, drawObject) => void

To see examples of draw handlers, you can check out default draw handlers in src/drawHandlerFunctions directory.

Custom handlers can be passed as a customDrawHandlers argument to createDrawFunction. customDrawHandlers should be an object, where keys represent object types and values represent custom handlers.