@joemaddalone/path

a simple svg path generation utility

Usage no npm install needed!

<script type="module">
  import joemaddalonePath from 'https://cdn.skypack.dev/@joemaddalone/path';
</script>

README

path

Install

npm install --save @joemaddalone/path

Basic Usage

import Path from 'path';

const Square = ({ x, y, size }) => {
  const path = new Path()
    .moveTo(x, y) // move pen to x, y
    .right(size) // draw line right to relative "size" px
    .down(size) // draw line down to relative "size" px
    .left(size) // draw line left to relative "size" px
    .close() // draw line back to first point
    .fill('green'); // set fill color
  return path.toElement();
};

Getting started

import Path from '@joemaddalone/path'

path is mostly helpful for building the commands needed for the "d" attribute of an svg path.

Most methods are direct translations from the SVG Path specification.

Example

<path d="M0 0, L0 100"></path>

This path can be produced with:

const path = new Path().M(0,0).L(0,100);
console.log(path.toString()) // M0 0, L0 100

Path Commands

For every svg path command there is an equivalent command available in path.

  • A(rx,ry,rotation,arc,sweep,ex,ey)
  • a(rx, ry,rotation,arc,sweep,ex,ey)
  • C(cx1,cy1,cx2,cy2,ex,ey)
  • c(cx1,cy1,cx2,cy2,ex,ey)
  • H(x)
  • h(x)
  • L(x,y)
  • l(x,y)
  • M(x,y)
  • m(x,y)
  • Q(cx,cy,ex,ey)
  • q(cx,cy,ex,ey)
  • S(cx,cy,ex,ey)
  • s(cx,cy,ex,ey)
  • T(ex,ey)
  • t(ex,ey)
  • V(y)
  • v(y)

And then for most of these is there is a semantically named helper method. Not required, but for complex paths it may be easier to read for those not familiar with path commmands.

  • arc(rx,ry,rotation,arc,sweep,ex,ey,relative = false)
    • relative is optional, its default is false. Setting relative to true is equivalent to a
  • cCurve(cx,cy,ex,ey,relative = false)
    • relative is optional, its default is false. Setting relative to true is equivalent to c
  • horizontalTo(x,relative = false)
    • relative is optional, its default is false. Setting relative to true is equivalent to h
  • verticalTo(x,relative = false)
    • relative is optional, its default is false. Setting relative to true is equivalent to v
  • lineTo(x,y,relative = false)
    • relative is optional, its default is false. Setting relative to true is equivalent to l
  • moveTo(x,y,relative = false)
    • relative is optional, its default is false. Setting relative to true is equivalent to m
  • qCurve(cx,cy,ex,ey,relative = false)
    • relative is optional, its default is false. Setting relative to true is equivalent to q
  • sCurveTo(cx,cy,ex,ey,relative = false)
    • relative is optional, its default is false. Setting relative to true is equivalent to s
  • tCurveTo(cx,cy,ex,ey,relative = false)
    • relative is optional, its default is false. Setting relative to true is equivalent to t

Some additional path command helpers:

  • down(px)
    • Draw line from current position down by px
  • up(px)
    • Draw line from current position up by px
  • right(px)
    • Draw line from current position right by px
  • left(px)
    • Draw line from current position left by px

One more path command helper

  • close()
    • Produces a "Z" command which draws a stright line back to the first point of the path.

Path Attributes

If you intend to output an actual path element and not just the set of commands attributes can be set on the element using the attr helper.

  • attr(key, value)
    • example: attr('id', 'my-id') will result in <path id="my-id"></path>

Built-in attribute helpers

  • fill(val)
  • stroke(val)
  • strokeWidth(val)
  • style(val)

Rendering

Depending on your needs there are few ways to use the data generated by path.

  • toArray
  • Returns an array of path commands
  • toString
    • Returns a string of path commands
  • toElement
    • Returns path element incuding attributes

Macros

Macros are a way to save a common set of path steps for reuse.

Example macro:

Path.macro('square', function (size, x, y) {
  return this.moveTo(x, y).right(size).down(size).left(size).up(size);
});

const p = new Path();
p.square(75, 18, 35);

These are so handy we have included a bunch!

Shapes

  • .circle(size, cx, cy)
    • .circle is drawn from center points (cx & cy). The cursor is then moved to the center points.
  • .cross(width, height, cx, cy)
    • .cross is drawn from center points (cx & cy). The cursor is then moved to the center points.
  • .ellipse(width, height, cx, cy)
    • .ellipse is drawn from center point (cx & cy). The cursor is then moved to the center point.
  • .lens(width, height, cx, cy)
    • .lens is drawn from center point (cx & cy). The cursor is then moved to the center point.
  • .omino(size, shape, sx, sy, lined = false)
    • .omino is drawn based on the positive values positioned in an 2d array. Think Tetris pieces.
  • .polygon([points])
    • .polygon accepts an array of [x, y] coordinates and then draws lines connecting those points. The path will start from the first point and end on the first point - closing the shape.
  • .polygram(size, points, cx, cy, vertexSkip = 2)
    • .polygram is drawn from center point (cx & cy). The first outer point of the shape will always be at top center. The cursor is then moved to the center point. Skipping a vertex is what makes a polygram appear as intersecting lines, a vertexSkip of 1 will result in a regular polygon.
  • .polyline([points], relative = false)
    • .polyline accepts an array of [x, y] coordinates and then draws lines connecting those points. The path will start from the first point and end on the last. points can be absolute or relative.
  • .radialLines(outerSize, innerSize, points, cx, cy)
    • .radialLines is drawn from center point (cx & cy). The first outer point of the shape will always be at top center. The cursor is then moved to the center point.
  • .rect(width, height, cx, cy)
    • .rect is drawn from center point (cx & cy). The cursor is then moved to the center point.
  • .regPolygon(size, sides, cx, cy)
    • .regPolygon is drawn from center point (cx & cy). The first outer point of the shape will always be at top center. The cursor is then moved to the center point.
  • .roundedRect(width, height, radius, cx, cy_)
    • .roundedRect is drawn from center point (cx & cy). The cursor is then moved to the center point.
  • .roundedSquare(size, radius, cx, cy)
    • .roundedSquare is drawn from center point (cx & cy). The cursor is then moved to the center point.
  • .sector(cx, cy, size, startAngle, endAngle)
    • .sector is drawn from center point (cx & cy). The cursor is then moved to the center point.
  • .segment(cx, cy, size, startAngle, endAngle)
    • .segment is drawn from center point (cx & cy). The cursor is then moved to the center point.
  • .square(size, cx, cy)
    • .square is drawn from center point (cx & cy). The cursor is then moved to the center point.
  • .star(outerSize, innerSize, points, cx, cy)
    • .star is drawn from center point (cx & cy). The first outer point of the shape will always be at top center. The cursor is then moved to the center point.
  • .symH(width, height, cx, cy)
    • .symH is drawn from center points (cx & cy). The cursor is then moved to the center points.
  • .symI(width, height, cx, cy)
    • .symI is drawn from center points (cx & cy). The cursor is then moved to the center points.
  • .symX(width, height, cx, cy)
    • .symX is drawn from center points (cx & cy). The cursor is then moved to the center points.
  • .triangle(size, cx, cy)
    • .triangle draws an equilateral triangle from center point (cx & cy). The cursor is then moved to the center point.

License

MIT © joemaddalone