Path

Creates a new Path item and places it at the top of the active layer.

Parameters:
• segments: Array of Segment objects — An array of segments (or points to be converted to segments) that will be added to the path. — optional

Example — Create an empty path and add segments to it:

var path = new Path();
path.strokeColor = 'black';
path.add(new Point(30, 30));
path.add(new Point(100, 100));

Example — Create a path with two segments:

var segments = [new Point(30, 30), new Point(100, 100)];
var path = new Path(segments);
path.strokeColor = 'black';

Creates a Path Item with two anchor points forming a line.

Parameters:
• pt1: Point — the first anchor point of the path
• pt2: Point — the second anchor point of the path

Returns:
• Path — the newly created path

Example

var from = new Point(20, 20);
var to = new Point(100, 100);
var path = new Path.Line(from, to);
path.strokeColor = 'black';

Creates a rectangle shaped Path Item from the passed point and size.

Parameters:
• point: Point
• size: Size

Returns:
• Path — the newly created path

Example

var point = new Point(100, 100);
var size = new Size(100, 100);
var rectangle = new Rectangle(point, size);
var path = new Path.Rectangle(rectangle);
path.strokeColor = 'black';

Creates a rectangle shaped Path Item from the passed points. These do not necessarily need to be the top left and bottom right corners, the constructor figures out how to fit a rectangle between them.

Parameters:
• point1: Point — The first point defining the rectangle
• point2: Point — The second point defining the rectangle

Returns:
• Path — the newly created path

Example

var point = new Point(100, 100);
var point2 = new Point(200, 300);
var path = new Path.Rectangle(point, point2);
path.strokeColor = 'black';

Creates a rectangle shaped Path Item from the passed abstract Rectangle.

Parameters:
• rect: Rectangle

Returns:
• Path — the newly created path

Example

var point = new Point(100, 100);
var size = new Size(100, 100);
var rectangle = new Rectangle(point, size);
var path = new Path.Rectangle(rectangle);
path.strokeColor = 'black';

Creates a rectangular Path Item with rounded corners.

Parameters:
• rect: Rectangle
• size: Size — the size of the rounded corners

Returns:
• Path — the newly created path

Example

var point = new Point(100, 100);
var size = new Size(100, 100);
var rectangle = new Rectangle(point, size);
var cornerSize = new Size(30, 30);
var path = new Path.RoundRectangle(rectangle, cornerSize);

Creates an oval shaped Path Item.

Parameters:
• rect: Rectangle
• circumscribed: Boolean — when set to true the oval shaped path will be created so the rectangle fits into it. When set to false the oval path will fit within the rectangle. — optional, default: false

Returns:
• Path — the newly created path

Example

var topLeft = new Point(100, 100);
var size = new Size(150, 100);
var rectangle = new Rectangle(topLeft, size);
var path = new Path.Oval(rectangle);
path.fillColor = 'black';

Creates a circle shaped Path Item.

Parameters:
• center: Point — the center point of the circle
• radius: Number — the radius of the circle

Returns:
• Path — the newly created path

Example

var path = new Path.Circle(new Point(100, 100), 50);

Creates a circular arc shaped Path Item.

Parameters:
• from: Point — the starting point of the circular arc
• through: Point — the point the arc passes through
• to: Point — the end point of the arc

Returns:
• Path — the newly created path

Example

var start = new Point(0, 0);
var through = new Point(100, 100);
var to = new Point(200, 150);
var path = new Path.Arc(start, through, to);
path.strokeColor = 'black';

Creates a regular polygon shaped Path Item.

Parameters:
• center: Point — the center point of the polygon
• numSides: Number — the number of sides of the polygon
• radius: Number — the radius of the polygon

Returns:
• Path — the newly created path

Example — Create a triangle shaped path

var center = new Point(100, 100);
var sides = 3;
var radius = 50;
var triangle = new Path.RegularPolygon(center, sides, radius);
triangle.fillColor = 'black';

Example — Create a decahedron shaped path

var center = new Point(100, 100);
var sides = 10;
var radius = 50;
var decahedron = new Path.RegularPolygon(center, sides, radius);
decahedron.fillColor = 'black';

Creates a star shaped Path Item.

The largest of radius1 and radius2 will be the outer radius of the star. The smallest of radius1 and radius2 will be the inner radius.

Parameters:
• center: Point — the center point of the star
• numPoints: Number — the number of points of the star
• radius1: Number
• radius2: Number

Returns:
• Path — the newly created path

Example

var center = new Point(100, 100);
var points = 6;
var radius1 = 20;
var radius2 = 50;
var path = new Path.Star(center, points, radius1, radius2);
path.fillColor = 'black';

The segments contained within the path.

Type:
• Array of Segment objects

The first Segment contained within the path.

Type:
• Segment

The last Segment contained within the path.

Type:
• Segment

The curves contained within the path.

Type:
• Array of Curve objects

The first Curve contained within the path.

Type:
• Curve

The last Curve contained within the path.

Type:
• Curve

Specifies whether the path is closed. If it is closed, Paper.js connects the first and last segments.

Type:
• Boolean

Example

Specifies whether the path and all its segments are selected.

Type:
• Boolean

Example — A path is fully selected, if all of its segments are selected:

Specifies whether the path is oriented clock-wise.

Type:
• Boolean

The length of the perimeter of the path.

Type:
• Number

Adds one or more segments to the end of the segments array of this path.

Parameters:
• segment: Segment / Point — the segment or point to be added.

Returns:
• Segment — the added segment. This is not necessarily the same object, e.g. if the segment to be added already belongs to another path.

Example — Adding segments to a path using point objects:

Example — Adding segments to a path using arrays containing number pairs:

Example — Adding segments to a path using objects:

Example — Adding a segment with handles to a path:

Inserts one or more segments at a given index in the list of this path's segments.

Parameters:
• index: Number — the index at which to insert the segment.
• segment: Segment / Point — the segment or point to be inserted.

Returns:
• Segment — the added segment. This is not necessarily the same object, e.g. if the segment to be added already belongs to another path.

Example — Inserting a segment:

Example — Inserting multiple segments:

Adds an array of segments (or types that can be converted to segments) to the end of the segments array.

Parameters:
• segments: Array of Segment objects

Returns:
• Array of Segment objects — an array of the added segments. These segments are not necessarily the same objects, e.g. if the segment to be added already belongs to another path.

Example — Adding an array of Point objects:

Example — Adding an array of [x, y] arrays:

Example — Adding segments from one path to another:

Inserts an array of segments at a given index in the path's segments array.

Parameters:
• index: Number — the index at which to insert the segments.
• segments: Array of Segment objects — the segments to be inserted.

Returns:
• Array of Segment objects — an array of the added segments. These segments are not necessarily the same objects, e.g. if the segment to be added already belongs to another path.

Removes the segment at the specified index of the path's segments array.

Parameters:
• index: Number — the index of the segment to be removed

Returns:
• Segment — the removed segment

Example — Removing a segment from a path:

Removes all segments from the path's segments array.

Returns:
• Array of Segment objects — an array containing the removed segments

Removes the segments from the specified from index to the to index from the path's segments array.

Parameters:
• from: Number — the beginning index, inclusive
• to: Number — the ending index, exclusive — optional, default: segments.length

Returns:
• Array of Segment objects — an array containing the removed segments

Example — Removing segments from a path:

Converts the curves in a path to straight lines with an even distribution of points. The distance between the produced segments is as close as possible to the value specified by the maxDistance parameter.

Parameters:
• maxDistance: Number — the maximum distance between the points

Example — Flattening a circle shaped path:

Smooths a path by simplifying it. The path.segments array is analyzed and replaced by a more optimal set of segments, reducing memory usage and speeding up drawing.

Parameters:
• tolerance: Number — optional, default: 2.5

Example — Click and drag below to draw to draw a line, when you release the mouse, the is made smooth using path.simplify():

Reverses the segments of the path.

Joins the path with the specified path, which will be removed in the process.

Parameters:
• path: Path

Example — Joining two paths:

Example — Joining two paths that share a point at the start or end of their segments array:

Example — Joining two paths that connect at two points:

Parameters:
• offset: Number
• isParameter: Boolean — optional, default: false

Returns:
• CurveLocation

Get the point on the path at the given offset.

Parameters:
• offset: Number
• isParameter: Boolean — optional, default: false

Returns:
• Point — the point at the given offset

Example — Finding the point on a path at a given offset:

Example — Iterating over the length of a path:

Get the tangent to the path at the given offset as a vector point.

Parameters:
• offset: Number
• isParameter: Boolean — optional, default: false

Returns:
• Point — the tangent vector at the given offset

Example — Working with the tangent vector at a given offset:

Example — Iterating over the length of a path:

Get the normal to the path at the given offset as a vector point.

Parameters:
• offset: Number
• isParameter: Boolean — optional, default: false

Returns:
• Point — the normal vector at the given offset

Example — Working with the normal vector at a given offset:

Example — Iterating over the length of a path:

Returns the nearest location on the path to the specified point.

Parameters:
• point: — {Point} The point for which we search the nearest location

Returns:
• CurveLocation — The location on the path that's the closest to the specified point

Returns the nearest point on the path to the specified point.

Parameters:
• point: — {Point} The point for which we search the nearest point

Returns:
• Point — The point on the path that's the closest to the specified point

Smooth bezier curves without changing the amount of segments or their points, by only smoothing and adjusting their handle points, for both open ended and closed paths.

Example — Smoothing a closed shape:

Example

If called on a CompoundPath, a new Path is created as a child and the point is added as its first segment. On a normal empty Path, the point is simply added as its first segment.

Parameters:
• point: Point

Parameters:
• point: Point

Adds a cubic bezier curve to the path, defined by two handles and a to point.

Parameters:
• handle1: Point
• handle2: Point
• to: Point

Adds a quadratic bezier curve to the path, defined by a handle and a to point.

Parameters:
• handle: Point
• to: Point

Draws a curve from the position of the last segment point in the path that goes through the specified through point, to the specified to point by adding one segment to the path.

Parameters:
• through: Point — the point through which the curve should go
• to: Point — the point where the curve should end
• parameter: Number — optional, default: 0.5

Example — Interactive example. Click and drag in the view below:

Draws an arc from the position of the last segment point in the path that goes through the specified through point, to the specified to point by adding one or more segments to the path.

Parameters:
• through: Point — the point where the arc should pass through
• to: Point — the point where the arc should end

Example

Example — Interactive example. Click and drag in the view below:

Draws an arc from the position of the last segment point in the path to the specified point by adding one or more segments to the path.

Parameters:
• to: Point — the point where the arc should end
• clockwise: Boolean — specifies whether the arc should be drawn in clockwise direction. — optional, default: true

Example

Example — Interactive example. Click and drag in the view below:

Closes the path. When closed, Paper.js connects the first and last segments.

See also: path.closed

If called on a CompoundPath, a new Path is created as a child and the point is added as its first segment relative to the position of the last segment of the current path.

Parameters:
• point: Point

Adds a segment relative to the last segment point of the path.

Parameters:
• vector: Point — The vector which is added to the position of the last segment of the path, to become the new segment.

Example

Example — Drawing a spiral using lineBy:

Parameters:
• throughVector: Point
• toVector: Point
• parameter: Number — optional, default: 0.5

Parameters:
• throughVector: Point
• toVector: Point

The unique id of the item.

Type:
• Number

The name of the item. If the item has a name, it can be accessed by name through its parent's children list.

Type:
• String

Example

The item's position within the project. This is the rectangle.center of the item's bounds rectangle.

Type:
• Point

Example — Changing the position of a path:

Example — Changing the x coordinate of an item's position:

The path style of the item.

Type:
• PathStyle

Example — Applying several styles to an item in one go, by passing an object to its style property:

Example — Copying the style of another item:

Example — Applying the same style object to multiple items:

Specifies whether the item is visible. When set to false, the item won't be drawn.

Default:
• true

Type:
• Boolean

Example — Hiding an item:

The blend mode of the item.

Default:
• 'normal'

Type:
• String('normal', 'multiply', 'screen', 'overlay', 'soft-light', 'hard-light', 'color-dodge', 'color-burn', 'darken', 'lighten', 'difference', 'exclusion', 'hue', 'saturation', 'luminosity', 'color', 'add', 'subtract', 'average', 'pin-light', 'negation')

Example — Setting an item's blend mode:

The opacity of the item as a value between 0 and 1.

Default:
• 1

Type:
• Number

Example — Making an item 50% transparent:

Specifies whether the item functions as a guide. When set to true, the item will be drawn at the end as a guide.

Default:
• 1

Type:
• Number

Specifies whether an item is selected and will also return true if the item is partially selected (groups with some selected or partially selected paths).

Paper.js draws the visual outlines of selected items on top of your project. This can be useful for debugging, as it allows you to see the construction of paths, position of path curves, individual segment points and bounding boxes of symbol and raster items.

Type:
• Boolean

See also: project.selectedItems, segment.selected, point.selected

Example — Selecting an item:

Specifies whether the item defines a clip mask. This can only be set on paths, compound paths, and text frame objects, and only if the item is already contained within a clipping group.

Type:
• Boolean

The project that this item belongs to.

Type:
• Project

The layer that this item is contained within.

Type:
• Layer

The item that this item is contained within.

Type:
• Item

Example

var path = new Path();

// New items are placed in the active layer:
console.log(path.parent == project.activeLayer); // true

var group = new Group();
group.addChild(path);

// Now the parent of the path has become the group:
console.log(path.parent == group); // true

The children items contained within this item. Items that define a name can also be accessed by name.

Please note: The children array should not be modified directly using array functions. To remove single items from the children list, use item.remove(), to remove all items from the children list, use item.removeChildren(). To add items to the children list, use item.addChild(item) or item.insertChild(index, item).

Type:
• Array of Item objects

Example — Accessing items in the children array:

Example — Accessing children by name:

Example — Passing an array of items to item.children:

The first item contained within this item. This is a shortcut for accessing item.children[0].

Type:
• Item

The last item contained within this item.This is a shortcut for accessing item.children[item.children.length - 1].

Type:
• Item

The next item on the same level as this item.

Type:
• Item

The previous item on the same level as this item.

Type:
• Item

The index of this item within the list of its parent's children.

Type:
• Number

The bounding rectangle of the item excluding stroke width.

Type:
• Rectangle

The bounding rectangle of the item including stroke width.

Type:
• Rectangle

The bounding rectangle of the item including handles.

Type:
• Rectangle

The color of the stroke.

Type:
• RgbColor / HsbColor / HslColor / GrayColor

Example — Setting the stroke color of a path:

The width of the stroke.

Type:
• Number

Example — Setting an item's stroke width:

The shape to be used at the end of open Path items, when they have a stroke.

Default:
• 'butt'

Type:
• String('round', 'square', 'butt')

Example — A look at the different stroke caps:

The shape to be used at the corners of paths when they have a stroke.

Default:
• 'miter'

Type:
• String ('miter', 'round', 'bevel')

Example — A look at the different stroke joins:

The dash offset of the stroke.

Default:
• 0

Type:
• Number

Specifies an array containing the dash and gap lengths of the stroke.

Default:
• []

Type:
• Array

Example

The miter limit of the stroke.

When two line segments meet at a sharp angle and miter joins have been specified for item.strokeJoin, it is possible for the miter to extend far beyond the item.strokeWidth of the path. The miterLimit imposes a limit on the ratio of the miter length to the item.strokeWidth.

Default:
• 10

Type:
• Number

The fill color of the item.

Type:
• RgbColor / HsbColor / HslColor / GrayColor

Example — Setting the fill color of a path to red:

Clones the item within the same project and places the copy above the item.

Returns:
• Item — the newly cloned item

Example — Cloning items:

When passed a project, copies the item to the project, or duplicates it within the same project. When passed an item, copies the item into the specified item.

Parameters:
• item: Project / Layer / Group / CompoundPath — the item or project to copy the item to

Returns:
• Item — the new copy of the item

Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization.

Parameters:
• resolution: Number — the resolution of the raster in dpi — optional, default: 72

Returns:
• Raster — the newly created raster item

Example — Rasterizing an item:

Perform a hit test on the item (and its children, if it is a Group or Layer) at the location of the specified point.

The optional options object allows you to control the specifics of the hit test and may contain a combination of the following values:

tolerance: Number - The tolerance of the hit test in points.

options.type: Only hit test again a certain item type: PathItem, Raster, TextItem, etc.

options.fill: Boolean - Hit test the fill of items.

options.stroke: Boolean - Hit test the curves of path items, taking into account stroke width.

options.segment: Boolean - Hit test for segment.point of Path items.

options.handles: Boolean - Hit test for the handles (segment.handleIn / segment.handleOut) of path segments.

options.ends: Boolean - Only hit test for the first or last segment points of open path items.

options.bounds: Boolean - Hit test the corners and side-centers of the bounding rectangle of items (item.bounds).

options.center: Boolean - Hit test the rectangle.center of the bounding rectangle of items (item.bounds).

options.guide: Boolean - Hit test items that have item.guide set to true.

options.selected: Boolean - Only hit selected items.

Parameters:
• point: Point — The point where the hit test should be performed
• options: Object — optional, default: { fill: true, stroke: true, segments: true, tolerance: 2 }

Returns:
• HitResult — A hit result object that contains more information about what exactly was hit or null if nothing was hit.

Adds the specified item as a child of this item at the end of the its children list. You can use this function for groups, compound paths and layers.

Parameters:
• item: Item — The item to be added as a child

Inserts the specified item as a child of this item at the specified index in its children list. You can use this function for groups, compound paths and layers.

Parameters:
• index: Number
• item: Item — The item to be appended as a child

Adds the specified items as children of this item at the end of the its children list. You can use this function for groups, compound paths and layers.

Parameters:
• items: item — The items to be added as children

Inserts the specified items as children of this item at the specified index in its children list. You can use this function for groups, compound paths and layers.

Parameters:
• index: Number
• items: Array of Item objects — The items to be appended as children

Inserts this item above the specified item.

Parameters:
• item: Item — The item above which it should be moved

Returns:
• Boolean — true it was inserted, false otherwise

Inserts this item below the specified item.

Parameters:
• item: Item — The item above which it should be moved

Returns:
• Boolean — true it was inserted, false otherwise

Inserts the specified item as a child of this item by appending it to the list of children and moving it above all other children. You can use this function for groups, compound paths and layers.

Parameters:
• item: Item — The item to be appended as a child

Inserts the specified item as a child of this item by appending it to the list of children and moving it below all other children. You can use this function for groups, compound paths and layers.

Parameters:
• item: Item — The item to be appended as a child

Moves this item above the specified item.

Parameters:
• item: Item — The item above which it should be moved

Returns:
• Boolean — true it was moved, false otherwise

Moves the item below the specified item.

Parameters:
• item: Item — the item below which it should be moved

Returns:
• Boolean — true it was moved, false otherwise

Removes the item from the project. If the item has children, they are also removed.

Returns:
• Boolean — true the item was removed, false otherwise

Removes all of the item's children (if any).

Returns:
• Array of Item objects — an array containing the removed items

Removes the children from the specified from index to the to index from the parent's children array.

Parameters:
• from: Number — the beginning index, inclusive
• to: Number — the ending index, exclusive — optional, default: children.length

Returns:
• Array of Item objects — an array containing the removed items

Reverses the order of the item's children

Checks if the item contains any children items.

Returns:
• Boolean — true it has one or more children, false otherwise

Checks if this item is above the specified item in the stacking order of the project.

Parameters:
• item: Item — The item to check against

Returns:
• Boolean — true if it is above the specified item, false otherwise

Checks if the item is below the specified item in the stacking order of the project.

Parameters:
• item: Item — The item to check against

Returns:
• Boolean — true if it is below the specified item, false otherwise

Checks whether the specified item is the parent of the item.

Parameters:
• item: Item — The item to check against

Returns:
• Boolean — true if it is the parent of the item, false otherwise

Checks whether the specified item is a child of the item.

Parameters:
• item: Item — The item to check against

Returns:
• Boolean — true it is a child of the item, false otherwise

Checks if the item is contained within the specified item.

Parameters:
• item: Item — The item to check against

Returns:
• Boolean — true if it is inside the specified item, false otherwise

Checks if the item is an ancestor of the specified item.

Parameters:
• item: Item — the item to check against

Returns:
• Boolean — true if the item is an ancestor of the specified item, false otherwise

Checks whether the item is grouped with the specified item.

Parameters:
• item: Item

Returns:
• Boolean — true if the items are grouped together, false otherwise

Scales the item by the given value from its center point, or optionally from a supplied point.

Parameters:
• scale: Number — the scale factor
• center: Point — optional, default: item.position

Example — Scaling an item from its center point:

Example — Scaling an item from a specific point:

Scales the item by the given values from its center point, or optionally from a supplied point.

Parameters:
• hor: Number — the horizontal scale factor
• ver: Number — the vertical scale factor
• center: Point — optional, default: item.position

Example — Scaling an item horizontally by 300%:

Translates (moves) the item by the given offset point.

Parameters:
• delta: Point — the offset to translate the item by

Rotates the item by a given angle around the given point.

Angles are oriented clockwise and measured in degrees.

Parameters:
• angle: Number — the rotation angle
• center: Point — optional, default: item.position

See also: matrix.rotate

Example — Rotating an item:

Example — Rotating an item around a specific point:

Shears the item by the given value from its center point, or optionally by a supplied point.

Parameters:
• point: Point
• center: Point — optional, default: item.position

See also: matrix.shear

Shears the item by the given values from its center point, or optionally by a supplied point.

Parameters:
• hor: Number — the horizontal shear factor.
• ver: Number — the vertical shear factor.
• center: Point — optional, default: item.position

See also: matrix.shear

Transform the item.

Parameters:
• matrix: Matrix
• flags:

Transform the item so that its bounds fit within the specified rectangle, without changing its aspect ratio.

Parameters:
• rectangle: Rectangle
• fill: Boolean — optional, default: false

Example — Fitting an item to the bounding rectangle of another item's bounding rectangle:

Example — Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true:

Example — Fitting an item to the bounding rectangle of the view

Removes the item when the events specified in the passed object literal occur.

The object literal can contain the following values:

Remove the item when the next tool.onMouseMove event is fired: object.move = true

Remove the item when the next tool.onMouseDrag event is fired: object.drag = true

Remove the item when the next tool.onMouseDown event is fired: object.down = true

Remove the item when the next tool.onMouseUp event is fired: object.up = true

Parameters:
• object: Object

Example — Click and drag below:

Removes the item when the next tool.onMouseMove event is fired.

Example — Move your mouse below:

Removes the item when the next tool.onMouseDown event is fired.

Example — Click a few times below:

Removes the item when the next tool.onMouseDrag event is fired.

Example — Click and drag below:

Removes the item when the next tool.onMouseUp event is fired.

Example — Click a few times below: