AreaText

Creates a text item that flows inside an area.

Parameters:

• area: PathItem — the path that the text flows inside
• orientation: String — the orientation of the text — optional, default: ‘horizontal’

Returns:

• AreaText — the newly created area text

Creates a text item that flows inside a rectangle.

Parameters:

• rectangle: Rectangle — the rectangle that the text flows inside
• orientation: String — the orientation of the text — optional, default: ‘horizontal’

Returns:

• AreaText — the newly created area text

Example:

Creates a text item that flows inside an area, from the properties described by an object literal.

Parameters:

• object: Object — an object containing properties describing the text’s attributes

Returns:

• AreaText — the newly created area text

The number of columns that the area is divided into, from left to right, which the text fills one after the other.

Default:

• 1

Type:

• Number

The number of rows that the area is divided into, from top to bottom, each with its columns.

Default:

• 1

Type:

• Number

The space between the columns and between the rows.

Default:

• 18

Type:

• Number

The space between the area’s edges and the text.

Default:

• 0

Type:

• Number

Where the lines sit in each column, from top to bottom.

Values:

• 'top', 'center', 'bottom'

Default:

• 'top'

Type:

• String

Sets the area’s height to the smallest that holds all of its text, scaling its textPath vertically from its top. An area without a height, which holds nothing, becomes a rectangle as wide as it.

Returns:

• AreaText — this area text

Example:

The key of the host’s node that the item represents, in a project backed by a host document, see project.host. It can only be set once, on an item created by a script, to register the key that the host gave its new node.

Type:

• Number

The unique id of the item.

Read only.

Type:

• Number

The class name of the item as a string.

Values:

• 'Group', 'Layer', 'Path', 'CompoundPath', 'Shape', 'Raster', 'SymbolItem', 'PointText'

Type:

• String

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 path style of the item.

Styles set on a Group or Layer are applied to the children that it contains at that moment. Items added to it later do not receive them.

Type:

• Style

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 locked. When set to true, item interactions with the mouse are disabled.

Default:

• false

Type:

• Boolean

Example:

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 with which the item is composited onto the canvas. Both the standard canvas compositing modes, as well as the new CSS blend modes are supported. Where the canvas doesn’t support a CSS blend mode natively, it draws as 'normal'. Paper.js’s own modes 'add', 'subtract', 'average', 'pin-light' and 'negation' are emulated, which can have an impact on performance.

Values:

• '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', 'source-over', 'source-in', 'source-out', 'source-atop', 'destination-over', 'destination-in', 'destination-out', 'destination-atop', 'lighter', 'darker', 'copy', 'xor'

Default:

• 'normal'

Type:

• String

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 is drawn as usual, but left out of hit-tests and mouse interactions. Hit-tests only find guides when options.guides is set, and then only them, see hitTest(point[, options]).

Default:

• false

Type:

• Boolean

Specifies whether, and how, the item pushes aside the text of the AreaText items below it in its layer: null, or an object with offset, the space kept between them, and invert, to let the text flow inside it instead. true sets the defaults.

Default:

• null

Type:

• Object

Example:

var circle = new Path.Circle({ center: [100, 100], radius: 40 });
circle.textWrap = { offset: 10 };

Specifies whether the item is selected. This will also return true for Group items if they are partially selected, e.g. groups containing 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.

Default:

• false

Type:

• Boolean

See also:

• project.selectedItems
• segment.selected
• curve.selected
• point.selected

Example:Selecting an item:

Specifies whether the item and all its descendants are selected. Setting it selects or deselects them all.

Type:

• Boolean

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

Default:

• false

Type:

• Boolean

A plain javascript object which can be used to store arbitrary data on the item.

Type:

• Object

Example:

var path = new Path();
path.data.remember = 'milk';

Example:

var path = new Path();
path.data.malcolm = new Point(20, 30);
console.log(path.data.malcolm.x); // 20

Example:

var path = new Path();
path.data = {
    home: 'Omicron Theta',
    found: 2338,
    pets: ['Spot']
};
console.log(path.data.pets.length); // 1

Example:

var path = new Path({
    data: {
        home: 'Omicron Theta',
        found: 2338,
        pets: ['Spot']
    }
});
console.log(path.data.pets.length); // 1

The item’s position within the parent item’s coordinate system. By default, 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 item’s pivot point specified in the item coordinate system, defining the point around which all transformations are hinging. This is also the reference point for position. By default, it is set to null, meaning the rectangle.center of the item’s bounds rectangle is used as pivot.

Default:

• null

Type:

• Point

The bounding rectangle of the item excluding stroke width.

Type:

• Rectangle

The bounding rectangle of the item including stroke width.

Setting it fits the item’s bounds into the given rectangle minus the extent of the stroke on each side, also where this extent changes with the item’s proportions, as with miters. A rectangle smaller than the stroke itself shrinks the bounds to its center.

Type:

• Rectangle

The bounding rectangle of the item including handles.

Type:

• Rectangle

The bounding rectangle of the item without any matrix transformations.

Typical use case would be drawing a frame around the object where you want to draw something of the same size, position, rotation, and scaling, like a selection frame.

Type:

• Rectangle

The current rotation angle of the item, as described by its matrix. Please note that this only returns meaningful values for items with applyMatrix set to false, meaning they do not directly bake transformations into their content.

Type:

• Number

The current scale factor of the item, as described by its matrix. Please note that this only returns meaningful values for items with applyMatrix set to false, meaning they do not directly bake transformations into their content.

Type:

• Point

The item’s transformation matrix, defining position and dimensions in relation to its parent item in which it is contained.

Type:

• Matrix

The item’s global transformation matrix in relation to the global project coordinate space. Note that the view’s transformations resulting from zooming and panning are not factored in.

Read only.

Type:

• Matrix

The item’s global matrix in relation to the view coordinate space. This means that the view’s transformations resulting from zooming and panning are factored in.

Read only.

Type:

• Matrix

Controls whether the transformations applied to the item (e.g. through transform(matrix), rotate(angle), scale(scale), etc.) are stored in its matrix property, or whether they are directly applied to its contents or children (passed on to the segments in Path items, the children of Group items, etc.).

Default:

• true

Type:

• Boolean

The project that this item belongs to.

Read only.

Type:

• Project

The view that this item belongs to.

Read only.

Type:

• View

The scope that this item belongs to, through its project.

Read only.

Type:

• PaperScope

The layer that this item is contained within.

Read only.

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

Example:Setting the parent of the item to another item

var path = new Path();

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

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

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

// The path is now contained in the children list of group:
console.log(group.children[0] == path); // true

Example:Setting the parent of an item in the constructor

var group = new Group();

var path = new Path({
    parent: group
});

// The parent of the path is the group:
console.log(path.parent == group); // true

// The path is contained in the children list of group:
console.log(group.children[0] == path); // true

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

Only Group, Layer and CompoundPath items can have children. On all other items, such as Path, Shape, Raster, SymbolItem and PointText, children is undefined.

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].

Read only.

Type:

• Item

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

Read only.

Type:

• Item

The next item on the same level as this item.

Read only.

Type:

• Item

The previous item on the same level as this item.

Read only.

Type:

• Item

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

Type:

• Number

The color of the stroke.

Type:

• Color⟋null

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 beginning and end of open Path items, when they have a stroke.

Values:

• 'round', 'square', 'butt'

Default:

• 'butt'

Type:

• String

Example:A look at the different stroke caps:

The shape to be used at the segments and corners of Path items when they have a stroke.

Values:

• 'miter', 'round', 'bevel'

Default:

• 'miter'

Type:

• String

Example:A look at the different stroke joins:

The dash offset of the stroke.

Default:

• 0

Type:

• Number

Specifies whether the stroke is to be drawn taking the current affine transformation into account (the default behavior), or whether it should appear as a non-scaling stroke. On text, non-scaling strokes are exact for uniform scaling only, as the glyphs are always stroked through the transformation.

Default:

• true

Type:

• Boolean

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

Default:

• []

Type:

• Array of Numbers

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 order in which the fill and the stroke are painted, as in SVG’s paint-order, named after what is painted first: 'fill' paints the fill first, 'stroke' paints the stroke first, so the fill covers its inner half.

Values:

• 'fill', 'stroke'

Default:

• 'fill'

Type:

• String

The fill color of the item.

Type:

• Color⟋null

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

The fill-rule with which the shape gets filled. Please note that only modern browsers support fill-rules other than 'nonzero'.

Values:

• 'nonzero', 'evenodd'

Default:

• 'nonzero'

Type:

• String

The shadow color.

Type:

• Color⟋null

Example:Creating a circle with a black shadow:

The shadow’s blur radius.

Default:

• 0

Type:

• Number

The shadow’s offset.

Default:

• 0

Type:

• Point

The color the item is highlighted with when selected. If the item does not specify its own color, the color defined by its layer is used instead.

Type:

• Color⟋null

Item level handler function to be called on each frame of an animation. The function receives an event object which contains information about the frame event:

Type:

• Function⟋null

Options:

• event.count: Number — the number of times the frame event was fired
• event.time: Number — the total amount of time passed since the first frame event in seconds
• event.delta: Number — the time passed in seconds since the last frame event

See also:

• view.onFrame

Example:Creating an animation:

The function to be called when the mouse button is pushed down on the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

• Function⟋null

See also:

• view.onMouseDown

Example:Press the mouse button down on the circle shaped path, to make it red:

Example:Press the mouse on the circle shaped paths to remove them:

The function to be called when the mouse position changes while the mouse is being dragged over the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

• Function⟋null

See also:

• view.onMouseDrag

Example:Press and drag the mouse on the blue circle to move it:

The function to be called when the mouse button is released over the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

• Function⟋null

See also:

• view.onMouseUp

Example:Release the mouse button over the circle shaped path, to make it red:

The function to be called when the mouse clicks on the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

• Function⟋null

See also:

• view.onClick

Example:Click on the circle shaped path, to make it red:

Example:Click on the circle shaped paths to remove them:

The function to be called when the mouse double clicks on the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

• Function⟋null

See also:

• view.onDoubleClick

Example:Double click on the circle shaped path, to make it red:

Example:Double click on the circle shaped paths to remove them:

The function to be called repeatedly while the mouse moves over the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

• Function⟋null

See also:

• view.onMouseMove

Example:Move over the circle shaped path, to change its opacity:

The function to be called when the mouse moves over the item. This function will only be called again, once the mouse moved outside of the item first. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

• Function⟋null

See also:

• view.onMouseEnter

Example:When you move the mouse over the item, its fill color is set to red. When you move the mouse outside again, its fill color is set back to black.

Example:When you click the mouse, you create new circle shaped items. When you move the mouse over the item, its fill color is set to red. When you move the mouse outside again, its fill color is set back to black.

The function to be called when the mouse moves out of the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

• Function⟋null

See also:

• view.onMouseLeave

Example:Move the mouse over the circle shaped path and then move it out of it again to set its fill color to red:

Sets the properties of the passed object literal on this item to the values defined in the object literal, if the item has property of the given name (or a setter defined for it).

Parameters:

• props: Object

Returns:

• Item — the item itself

Example:Setting properties through an object literal

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

Options:

• insert: undefined — specifies whether the copy should be inserted into the scene graph. When set to true, it is inserted above the original — default: true
• deep: undefined — specifies whether the item’s children should also be cloned — default: true

Parameters:

• options: Object — optional, default: { insert: true, deep: true }

Returns:

• Item — the newly cloned item

Example:Cloning items:

Copies the content of the specified item over to this item.

Parameters:

• source: Item — the item to copy the content from

Copies all attributes of the specified item over to this item. This includes its style, visibility, matrix, pivot, blend-mode, opacity, selection state, data, name, etc.

Parameters:

• source: Item — the item to copy the attributes from
• excludeMatrix: Boolean — whether to exclude the transformation matrix when copying all attributes

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

Options:

• options.resolution: Number — the desired resolution to be used when rasterizing, in pixels per inch (DPI). If not specified, the value of view.resolution is used by default. — default: view.resolution
• options.raster: Raster — specifies a raster to be reused when rasterizing. If the raster has the desired size already, then the underlying canvas is reused and no new memory needs to be allocated. If no raster is provided, a new raster item is created and returned instead. — default: null
• options.insert: Boolean — specifies whether the raster should be inserted into the scene graph. When set to true, it is inserted above the rasterized item. — default: true

Parameters:

• options: Object — the rasterization options — optional, default: {}

Returns:

• Raster — the reused raster or the newly created raster item

Example:Rasterizing an item:

Checks whether the item’s geometry contains the given point.

Parameters:

• point: Point — the point to check for

Returns:

• Boolean

Example:Click within and outside the star below Create a star shaped path:

Parameters:

• rect: Rectangle — the rectangle to check against

Returns:

• Boolean

Checks whether the item overlaps with the given item: whether their outlines cross, or one contains the other, as rectangle.intersects(rect) does for rectangles. Items other than paths and shapes are checked through their bounds. To only check whether outlines cross, use pathItem.getIntersections(path).

Parameters:

• item: Item — the item to check against

Returns:

• Boolean — true if the items overlap, false otherwise

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

The options object allows you to control the specifics of the hit-test. Without options, fill, stroke and segments are hit-tested. As soon as an options object is passed, only the hit-tests that it sets to true are performed. It may contain a combination of the following values:

Options:

• options.tolerance: Number — the tolerance of the hit-test, in project coordinates — default: paperScope.settings.hitTolerance
• options.class: Function — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an instanceof check is performed: Group, Layer, Path, CompoundPath, Shape, Raster, SymbolItem, PointText, …
• options.match: Function — a match function to be called for each found hit result: Return true to return the result, false to keep searching
• options.fill: Boolean — hit-test the fill of items
• options.stroke: Boolean — hit-test the stroke of path items, taking into account the setting of stroke color and width
• options.segments: Boolean — hit-test for segment.point of Path items
• options.curves: Boolean — hit-test the curves of path items, without taking the stroke color or width into account
• 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.position: Boolean — hit-test the item.position of of items, which depends on the setting of item.pivot
• options.center: Boolean — hit-test the rectangle.center of the bounding rectangle of items (item.bounds)
• options.bounds: Boolean — hit-test the corners and side-centers of the bounding rectangle of items (item.bounds)
• options.guides: Boolean — only 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 (in global coordinates system).
• options: Object — optional, default: { fill: true, stroke: true, segments: true, tolerance: settings.hitTolerance }

Returns:

• HitResult — a hit result object describing what exactly was hit or null if nothing was hit

Performs a hit-test on the item and its children (if it is a Group or Layer) at the location of the specified point, returning all found hits.

The options object allows you to control the specifics of the hit- test. See hitTest(point[, options]) for a list of all options.

Parameters:

• point: Point — the point where the hit-test should be performed (in global coordinates system).
• options: Object — optional, default: { fill: true, stroke: true, segments: true, tolerance: settings.hitTolerance }

Returns:

• Array of HitResult objects — hit result objects for all hits, describing what exactly was hit or null if nothing was hit

See also:

• hitTest(point[, options]);

Checks whether the item matches the criteria described by the given object, by iterating over all of its properties and matching against their values through matches(name, compare).

See project.getItems(options) for a selection of illustrated examples.

Parameters:

• options: Object⟋Function — the criteria to match against

Returns:

• Boolean — true if the item matches all the criteria, false otherwise

See also:

• getItems(options)

Checks whether the item matches the given criteria. Extended matching is possible by providing a compare function or a regular expression. Matching points, colors only work as a comparison of the full object, not partial matching (e.g. only providing the x-coordinate to match all points with that x-value). Partial matching does work for item.data.

See project.getItems(options) for a selection of illustrated examples.

Parameters:

• name: String — the name of the state to match against
• compare: Object — the value, function or regular expression to compare against

Returns:

• Boolean — true if the item matches the state, false otherwise

See also:

• getItems(options)

Fetch the descendants (children or children of children) of this item that match the properties in the specified object. Extended matching is possible by providing a compare function or regular expression. Matching points, colors only work as a comparison of the full object, not partial matching (e.g. only providing the x- coordinate to match all points with that x-value). Partial matching does work for item.data.

Matching items against a rectangular area is also possible, by setting either options.inside or options.overlapping to a rectangle describing the area in which the items either have to be fully or partly contained.

See project.getItems(options) for a selection of illustrated examples.

Options:

• options.recursive: Boolean — whether to loop recursively through all children, or stop at the current level — default: true
• options.match: Function — a match function to be called for each item, allowing the definition of more flexible item checks that are not bound to properties. If no other match properties are defined, this function can also be passed instead of the options object
• options.class: Function — the constructor function of the item type to match against
• options.inside: Rectangle — the rectangle in which the items need to be fully contained
• options.overlapping: Rectangle — the rectangle with which the items need to at least partly overlap

Parameters:

• options: Object⟋Function — the criteria to match against

Returns:

• Array of Item objects — the list of matching descendant items, in their stacking order from bottom to top, with each item listed before its own descendants

See also:

• matches(options)

Fetch the first descendant (child or child of child) of this item that matches the properties in the specified object. Extended matching is possible by providing a compare function or regular expression. Matching points, colors only work as a comparison of the full object, not partial matching (e.g. only providing the x- coordinate to match all points with that x-value). Partial matching does work for item.data. See project.getItems(match) for a selection of illustrated examples.

Parameters:

• options: Object⟋Function — the criteria to match against

Returns:

• Item — the first descendant item matching the given criteria

See also:

• getItems(options)

Exports (serializes) the item with its content and child items to a JSON data string.

Options:

• options.asString: Boolean — whether the JSON is returned as a Object or a String — default: true
• options.precision: Number — the amount of fractional digits in numbers used in JSON data — default: 5

Parameters:

• options: Object — the serialization options — optional

Returns:

• String — the exported JSON data

Imports (deserializes) the stored JSON data into this item. If the data describes an item of the same class or a parent class of the item, the data is imported into the item itself. If not, the imported item is added to this item’s item.children list. Note that not all type of items can have children.

Parameters:

• json: String — the JSON data to import from

Returns:

• Item

Exports the item with its content and child items as an SVG DOM.

Options:

• options.bounds: String⟋Rectangle — the bounds of the area to export, either as a string (‘view’, content’), or a Rectangle object: 'view' uses the view bounds, 'content' uses the stroke bounds of all content — default: ‘view’
• options.matrix: Matrix — the matrix with which to transform the exported content: If options.bounds is set to 'view', paper.view.matrix is used, for all other settings of options.bounds the identity matrix is used. — default: paper.view.matrix
• options.asString: Boolean — whether a SVG node or a String is to be returned — default: false
• options.precision: Number — the amount of fractional digits in numbers used in SVG data — default: 5
• options.matchShapes: Boolean — whether path items should tried to be converted to SVG shape items (rect, circle, ellipse, line, polyline, polygon), if their geometries match — default: false
• options.embedImages: Boolean — whether raster images should be embedded as base64 data inlined in the xlink:href attribute, or kept as a link to their external URL. — default: true
• options.reuseImages: Boolean — whether raster images with the same content should only be exported once into the <defs> element, and placed through <use> elements referencing it — default: false
• options.idPrefix: String — a prefix for the ids generated for definitions such as gradients, clip paths and symbols, to keep them unique when several exported SVGs are placed in one document — default: ’’
• options.reduceAttributes: Boolean — wether to only include style attributes in the SVG output that differ from their parents, or to always include them (much faster but leading to redundancies). — default: true
• [options.processNode] {Function} the function to process the SVG node made for each exported item, receiving an object with the `item` and its `node`: It can change the node, e.g. to add attributes that Paper.js doesn't export, or return a node to replace it with. It is called before the item's name, style, visibility and data are set on the node, which replace attributes of the same names.

Parameters:

• options: Object — the export options — optional

Returns:

• SVGElement⟋String — the item converted to an SVG node or a String depending on option.asString value

Converts the provided SVG content into Paper.js items and adds them to the this item’s children list. Note that the item is not cleared first. You can call item.removeChildren() to do so.

<symbol> elements are imported as SymbolDefinition items, and the <use> elements that place them as SymbolItem items. The styles that <use> elements inherit don’t reach the symbols’ content.

The layers in SVG content that Paper.js exported come back as Layer items inside the imported group. To make the layers of a project’s SVG the layers of a project again, add them to it with item.children.slice().forEach(project.addLayer, project).

URLs are fetched as they are, so validate URLs that come from untrusted sources first, especially on servers, where they could reach internal addresses.

Options:

• options.expandShapes: Boolean — whether imported shape items should be expanded to path items — default: false
• [options.crossOrigin] {String} the {@link Raster#crossOrigin} value of the rasters created for `` elements, to load their images with CORS
• options.onLoad: Function — the callback function to call once the SVG content is loaded from the given URL receiving two arguments: the converted item and the original svg data as a string. Only required when loading from external resources.
• options.onError: Function — the callback function to call if an error occurs during loading. Only required when loading from external resources.
• options.insert: Boolean — whether the imported items should be added to the item that importSVG() is called on — default: true
• options.applyMatrix: Boolean — whether the imported items should have their transformation matrices applied to their contents or not — default: paperScope.settings.applyMatrix
• [options.processItem] {Function} the function to process the item made for each imported SVG element, receiving an object with the `item` and its `node`: It can read attributes that Paper.js doesn't import, or return an item to replace it with. It is called after the element's attributes and data are applied to the item, so it can extend `item.data`. A replacement item doesn't receive them: copy them over from `item` as needed.

Parameters:

• svg: SVGElement⟋String — the SVG content to import, either as a SVG DOM node, a string containing SVG content, or a string describing the URL of the SVG file to fetch.
• options: Object — the import options — optional

Returns:

• Item — the newly created Paper.js item containing the converted SVG content

Imports the provided external SVG file, converts it into Paper.js items and adds them to the this item’s children list. Note that the item is not cleared first. You can call item.removeChildren() to do so.

Parameters:

• svg: SVGElement⟋String — the URL of the SVG file to fetch.
• onLoad: Function — the callback function to call once the SVG content is loaded from the given URL receiving two arguments: the converted item and the original svg data as a string. Only required when loading from external files.

Returns:

• Item — the newly created Paper.js item containing the converted SVG content

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

Returns:

• Item — the added item, or null if adding was not possible

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 — the index at which to insert the item
• item: Item — the item to be inserted as a child

Returns:

• Item — the inserted item, or null if inserting was not possible

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: Array of Item objects — the items to be added as children

Returns:

• Array of Item objects — the added items, or null if adding was not possible

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

Returns:

• Array of Item objects — the inserted items, or null if inserted was not possible

Inserts this item above the specified item.

Parameters:

• item: Item — the item above which it should be inserted

Returns:

• Item — the inserted item, or null if inserting was not possible

Inserts this item below the specified item.

Parameters:

• item: Item — the item below which it should be inserted

Returns:

• Item — the inserted item, or null if inserting was not possible

Sends this item to the back of all other items within the same parent.

Brings this item to the front of all other items within the same parent.

Adds it to the specified owner, which can be either a Item or a Project.

Parameters:

• owner: Project⟋Layer⟋Group⟋CompoundPath — the item or project to add the item to

Returns:

• Item — the item itself, if it was successfully added

Clones the item and adds it to the specified owner, which can be either a Item or a Project.

Parameters:

• owner: Project⟋Layer⟋Group⟋CompoundPath — the item or project to copy the item to

Returns:

• Item — the new copy of the item, if it was successfully added

If this is a group, layer or compound-path with only one child-item, the child-item is moved outside and the parent is erased. Otherwise, the item itself is returned unmodified.

Parameters:

• options: Object — the options passed on to path.reduce(options) — optional

Returns:

• Item — the reduced item

Removes the item and all its children from the project. The item is not destroyed and can be inserted again after removal.

Returns:

• Boolean — true if the item was removed, false otherwise

Replaces this item with the provided new items which will take its place in the project hierarchy instead, in the given order. This also ungroups a group, e.g. group.replaceWith(…group.children), but note that the items keep their own matrices, see group.ungroup().

Parameters:

• item: Item — the items that will replace this item

Returns:

• Boolean — true if the item was replaced, 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 start index to and excluding the end index from the parent’s children array.

Parameters:

• start: Number — the beginning index, inclusive
• end: 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

Specifies whether the item has any content or not. The meaning of what content is differs from type to type. For example, a Group with no children, a TextItem with no text content and a Path with no segments all are considered empty.

Parameters:

• recursively: Boolean — whether an item with children should be considered empty if all its descendants are empty — optional, default: false

Returns:

• Boolean

Checks whether the item has a visible fill, a fill color with an alpha above 0. Hit-tests also hit transparent fills, see hitTest.

Returns:

• Boolean — true if the item has a visible fill, false otherwise

Checks whether the item has a stroke.

Returns:

• Boolean — true if the item has a stroke, false otherwise

Checks whether the item has a shadow.

Returns:

• Boolean — true if the item has a shadow, false otherwise

Checks if the item contains any children items.

Returns:

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

Checks whether the item and all its parents are inserted into scene graph or not.

Returns:

• Boolean — true if the item is inserted into the scene graph, false otherwise

Checks if this item is above the specified item in the stacking order of the project. If one item is a descendant of the other, neither is above the other and false is returned.

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. If one item is a descendant of the other, neither is below the other and false is returned.

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 if the item is an a sibling of the specified item.

Parameters:

• item: Item — the item to check against

Returns:

• Boolean — true if the item is aa sibling 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

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

Parameters:

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

Rotates the item by a given angle around the given center 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(angle[, center])

Example:Rotating an item:

Example:Rotating an item around a specific point:

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%:

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

Parameters:

• shear: Point — the horizontal and vertical shear factors as a point
• center: Point — optional, default: item.position

See also:

• matrix.shear(shear[, center])

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(hor, ver[, center])

Skews the item by the given angles from its center point, or optionally by a supplied point.

Parameters:

• skew: Point — the horizontal and vertical skew angles in degrees
• center: Point — optional, default: item.position

See also:

• matrix.shear(skew[, center])

Skews the item by the given angles from its center point, or optionally by a supplied point.

Parameters:

• hor: Number — the horizontal skew angle in degrees
• ver: Number — the vertical sskew angle in degrees
• center: Point — optional, default: item.position

See also:

• matrix.shear(hor, ver[, center])

Transform the item.

Parameters:

• matrix: Matrix — the matrix by which the item shall be transformed

Converts the specified point from global project coordinate space to the item’s own local coordinate space.

Parameters:

• point: Point — the point to be transformed

Returns:

• Point — the transformed point as a new instance

Converts the specified point from the item’s own local coordinate space to the global project coordinate space.

Parameters:

• point: Point — the point to be transformed

Returns:

• Point — the transformed point as a new instance

Converts the specified point from the parent’s coordinate space to item’s own local coordinate space.

Parameters:

• point: Point — the point to be transformed

Returns:

• Point — the transformed point as a new instance

Converts the specified point from the item’s own local coordinate space to the parent’s coordinate space.

Parameters:

• point: Point — the point to be transformed

Returns:

• Point — the transformed point as a new instance

Transform the item so that its bounds are centered in the specified rectangle and fitted to it as described by fit.

Parameters:

• rectangle: Rectangle
• fit: String⟋Boolean — how to fit the item, as in CSS’s object-fit: 'contain' fits all of it within the rectangle, 'cover' makes it cover the whole rectangle, and 'fill' stretches it to the rectangle, changing its aspect ratio. The deprecated true and false stand for 'cover' and 'contain'. — optional, default: ‘contain’

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, covering all of it:

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

Attaches an event handler to the item.

Parameters:

• type: String — the type of event: ‘frame’, mousedown’, ‘mouseup’, ‘mousedrag’, ‘click’, ‘doubleclick’, ‘mousemove’, ‘mouseenter’, ‘mouseleave’
• function: Function — the function to be called when the event occurs, receiving a MouseEvent or Event object as its sole argument

Returns:

• Item — this item itself, so calls can be chained

Example:Change the fill color of the path to red when the mouse enters its shape and back to black again, when it leaves its shape.

Attaches one or more event handlers to the item.

Parameters:

• object: Object — an object containing one or more of the following properties: frame, mousedown, mouseup, mousedrag, click, doubleclick, mousemove, mouseenter, mouseleave

Returns:

• Item — this item itself, so calls can be chained

Example:Change the fill color of the path to red when the mouse enters its shape and back to black again, when it leaves its shape.

Example:When you click the mouse, you create new circle shaped items. When you move the mouse over the item, its fill color is set to red. When you move the mouse outside again, its fill color is set black.

Detach an event handler from the item.

Parameters:

• type: String — the type of event: ‘frame’, mousedown’, ‘mouseup’, ‘mousedrag’, ‘click’, ‘doubleclick’, ‘mousemove’, ‘mouseenter’, ‘mouseleave’
• function: Function — the function to be detached

Returns:

• Item — this item itself, so calls can be chained

Detach one or more event handlers to the item.

Parameters:

• object: Object — an object containing one or more of the following properties: frame, mousedown, mouseup, mousedrag, click, doubleclick, mousemove, mouseenter, mouseleave

Returns:

• Item — this item itself, so calls can be chained

Emit an event on the item.

Parameters:

• type: String — the type of event: ‘frame’, mousedown’, ‘mouseup’, ‘mousedrag’, ‘click’, ‘doubleclick’, ‘mousemove’, ‘mouseenter’, ‘mouseleave’
• event: Object — an object literal containing properties describing the event

Returns:

• Boolean — true if the event had listeners, false otherwise

Check if the item has one or more event handlers of the specified type.

Parameters:

• type: String — the type of event: ‘frame’, mousedown’, ‘mouseup’, ‘mousedrag’, ‘click’, ‘doubleclick’, ‘mousemove’, ‘mouseenter’, ‘mouseleave’

Returns:

• Boolean — true if the item has one or more event handlers of the specified type, false otherwise

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

Options:

• options.move: Boolean — remove the item when the next tool.onMouseMove event is fired.
• options.drag: Boolean — remove the item when the next tool.onMouseDrag event is fired.
• options.down: Boolean — remove the item when the next tool.onMouseDown event is fired.
• options.up: Boolean — remove the item when the next tool.onMouseUp event is fired.

Parameters:

• options: 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:

Tween item between two states.

Options:

• options.duration: Number — the duration of the tweening
• options.easing: Function⟋String — an easing function or the type of the easing: ‘linear’ ‘easeInQuad’ ‘easeOutQuad’ ‘easeInOutQuad’ ‘easeInCubic’ ‘easeOutCubic’ ‘easeInOutCubic’ ‘easeInQuart’ ‘easeOutQuart’ ‘easeInOutQuart’ ‘easeInQuint’ ‘easeOutQuint’ ‘easeInOutQuint’ ‘easeInSine’ ‘easeOutSine’ ‘easeInOutSine’ ‘easeInExpo’ ‘easeOutExpo’ ‘easeInOutExpo’ ‘easeInCirc’ ‘easeOutCirc’ ‘easeInOutCirc’ — default: ‘linear’
• options.start: Boolean — whether to start tweening automatically — default: true

Parameters:

• from: Object — the state at the start of the tweening
• to: Object — the state at the end of the tweening
• options: Object⟋Number — the options or the duration

Returns:

• Tween

Example:Tween fillColor:

Example:Tween rotation:

Tween item to a state.

Parameters:

• to: Object — the state at the end of the tweening
• options: Object⟋Number — the options or the duration

Returns:

• Tween

See also:

• item.tween(from, to, options)

Example:Tween a nested property with relative values

Tween item.

Parameters:

• options: Object⟋Number — the options or the duration

Returns:

• Tween

See also:

• item.tween(from, to, options)

Example:Start an empty tween and just use the update callback:

Tween item to a state.

Parameters:

• to: Object — the state at the end of the tweening
• options: Object⟋Number — the options or the duration

Returns:

• Tween

See also:

• item.tween(to, options)

Tween item from a state to its state before the tweening.

Parameters:

• from: Object — the state at the start of the tweening
• options: Object⟋Number — the options or the duration

Returns:

• Tween

See also:

• item.tween(from, to, options)

Example:Tween fillColor from red to the path's initial fillColor:

The direction the text’s lines run in: 'horizontal', or 'vertical' from top to bottom, with the lines from right to left.

Default:

• 'horizontal'

Type:

• String

The path that the text flows in (AreaText) or along (PathText). It guides the text and isn’t drawn itself.

Type:

• PathItem

The story the text item shows: the text of all the text items linked with it.

Read only.

Type:

• TextStory

The text item after this one in its story, if any.

Read only.

Type:

• TextItem

The text item before this one in its story, if any.

Read only.

Type:

• TextItem

The range of the story that this text item shows, as its layout flows the story through the linked text items: without the overflow, and without what the ones before it show.

Read only.

Type:

• TextRange

The lines of the text, as its layout breaks them: each a range of its story, with its baseline, a Line along it, and its bounds, in the text item’s own coordinates. A PathText’s one line follows its path: these describe it laid out straight.

Read only.

Type:

• Array of TextRange objects

The font-family to be used in text content.

Default:

• 'sans-serif'

Type:

• String

The font-weight to be used in text content.

Default:

• 'normal'

Type:

• String⟋Number

The font size of text content, as a number in pixels, or as a string with optional units 'px', 'pt' and 'em'.

Default:

• 10

Type:

• Number⟋String

The line height of text content: the distance from one line’s baseline to the next. Automatic, as 'auto' (1.2) or another factor of the letters’ font size, each line moving down by its largest letters’; or fixed, as a length with units as the font size takes them ('18px', '12pt'). leading, as Paper.js had it before, sets and reads it as a fixed length in pixels.

Default:

• 'auto'

Type:

• Number⟋String

The letter tracking of text content: the space added after each letter, along the line, in thousandths of an em, as in Adobe Illustrator and InDesign. A tracking of 100 adds a tenth of the font size. Also tracking, its former name.

Default:

• 0

Type:

• Number

The letter kerning of text content: the space added after a letter, along the line, in thousandths of an em, in place of the font’s own kerning pair; null for the font’s kerning.

Default:

• null

Type:

• Number

The font style of text content, as in CSS: upright or slanted. Together with the fontWeight, it says what a font’s style name says, e.g. 'Bold Italic'.

Values:

• 'normal', 'italic', 'oblique'

Default:

• 'normal'

Type:

• String

The settings of a variable font’s axes, by their tags: { wght: 600, wdth: 80 }. Kept for hosts that lay text out with its fonts; canvas doesn’t draw them.

Default:

• null

Type:

• Object

How far the letters move up from the baseline, in pixels.

Default:

• 0

Type:

• Number

Whether the letters are set as superscripts or subscripts: smaller, and above or below the baseline.

Values:

• 'normal', 'superscript', 'subscript'

Default:

• 'normal'

Type:

• String

How much the letters are scaled, as item.scaling: one factor for both directions, or a point with the horizontal and vertical ones.

Default:

• 1

Type:

• Number⟋Point

The rotation of each letter about its origin on the baseline, in degrees.

Default:

• 0

Type:

• Number

Whether the letters are set as capitals, or as small capitals.

Values:

• 'normal', 'all', 'small'

Default:

• 'normal'

Type:

• String

Whether the letters are underlined.

Default:

• false

Type:

• Boolean

Whether the letters are struck through.

Default:

• false

Type:

• Boolean

The OpenType features to turn on ('dlig') or off ('-liga'). Kept for hosts that lay text out with its fonts; canvas doesn’t draw them.

Default:

• null

Type:

• Array of Strings

The justification of text paragraphs.

Values:

• 'left', 'right', 'center', 'start', 'end', 'justify'

Default:

• 'left'

Type:

• String

How the last line of a justified paragraph is aligned; 'all' justifies it too.

Values:

• 'left', 'right', 'center', 'start', 'end', 'all'

Default:

• 'left'

Type:

• String

How far justification may change the spacing, each as [minimum, desired, maximum] in percent: { word: [80, 100, 133], letter: [0, 0, 0], glyph: [100, 100, 100] }; null for those. Kept for hosts: canvas text justifies by the word spacing alone.

Default:

• null

Type:

• Object

The indent where the paragraph’s lines start: left in left-to-right text, right in right-to-left text.

Default:

• 0

Type:

• Number

The indent where the paragraph’s lines end.

Default:

• 0

Type:

• Number

The indent of the paragraph’s first line, added to its start indent.

Default:

• 0

Type:

• Number

The space above the paragraph. Between two paragraphs, the larger of this one’s and the space after the one before it is used.

Default:

• 0

Type:

• Number

The space below the paragraph.

Default:

• 0

Type:

• Number

Whether words are hyphenated at the ends of lines, and how: true, or { wordsLongerThan, afterFirst, beforeLast, limit, zone, capitalized }. Kept for hosts: canvas text breaks only at soft hyphens.

Default:

• false

Type:

• Boolean⟋Object

How lines are broken: one line at a time, or all of the paragraph’s lines together, for the most even spacing. Kept for hosts: canvas text breaks one line at a time.

Values:

• 'line', 'paragraph'

Default:

• 'paragraph'

Type:

• String

How the lines of a paragraph in an area are evened out: 'normal' fills each line as far as it goes, 'balance' makes them all about as long, and 'pretty' balances the last four lines when the last one is shorter than a third of the one before. Both keep the paragraph’s number of lines.

Values:

• 'normal', 'balance', 'pretty'

Default:

• 'normal'

Type:

• String

The paragraph’s tab stops: [{ position, align, leader }], with align one of 'left', 'center', 'right' and 'decimal'. Kept for hosts: canvas text doesn’t set tabs yet.

Default:

• null

Type:

• Array of Object objects

The direction the paragraph’s lines run in, which 'start' and 'end' follow, and from which side their pieces are placed; null for left to right. Lines that mix directions across styles aren’t reordered by the Unicode bidirectional algorithm: their pieces follow the paragraph’s direction, and canvas orders only the letters within each piece.

Values:

• 'ltr', 'rtl'

Default:

• null

Type:

• String

The text of the item’s story, see textStory.content.

Type:

• String

The runs of the item’s story, see textStory.runs.

Type:

• Array of TextRange objects

The paragraphs of the item’s story, see textStory.paragraphs.

Type:

• Array of TextRange objects

The words of the item’s story, see textStory.words.

Type:

• Array of TextRange objects

The letters of the item’s story, see textStory.letters.

Type:

• Array of TextRange objects

Links the text item next after this one, so the story flows on into it. Its own story joins the end of this one.

Parameters:

• next: TextItem — the text item to link

Returns:

• Boolean — true if the text item was linked, false otherwise

true if the text item is linked with others, false otherwise

Returns:

• Boolean

Unlinks the text item: 'both' takes it out of its story, which flows on through the others, 'before' and 'after' break the story into two there.

Parameters:

• which: String — 'both', 'before' or 'after' — optional, default: ‘both’

Returns:

• Boolean — true if the text item was unlinked, false otherwise

Replaces the content from start to end of the item’s story, see textStory.replace(content, start, end).

Parameters:

• content: String — the new content
• start: Number — the index of the first character to replace
• end: Number — the index after the last character to replace

The range of the item’s story from start to end.

Parameters:

• start: Number — the index of its first character
• end: Number — the index after its last character

Returns:

• TextRange