react-xarrows

see details

required
can be a reference to a react ref to html element or string - an id of a DOM element.

examples:

• start="myid" - myid is id of a dom element.
• start={myRef} - myRef is a react ref.

specify what anchors are allowed. can be a string/object/array.

type:

export type anchorType = anchorPositionType | anchorCustomPositionType;

simple usage:

type:

export const tAnchorEdge = ['middle', 'left', 'right', 'top', 'bottom', 'auto'] as const;
export type anchorPositionType = typeof tAnchorEdge[number];

one of "auto" | "middle" | "left" | "right" | "top" | "bottom" auto will choose automatically the path with the smallest length.

example:

• endAnchor="middle" will set the anchor of the end of the line to the middle of the end element.

custom usage:

type:

export type anchorCustomPositionType = {
    position: anchorPositionType;
    offset: { rightness?: number; bottomness?: number };
};

you can offset the anchor from normal positioning. NOTE: breaking changes in naming in v2.

example:

• endAnchor= { position: "auto", offset: { rightness: 20 } } will choose automatic anchoring for end anchor but will offset it 20 pixels to the right after normal positioning.

if list is provided - the minimal length anchors will be chosen from the list. example:

• endAnchor= ["right", {position: "left", offset: {bottomness: -10}}] only right and left anchors will be allowed for endAnchor, and if the left side connected then it will be offset 10 pixels up.

you can place up to 3 labels. see examples

• label="middleLabel" - middle label
• label=<div style={{ fontSize: "1.3em", fontFamily: "fantasy", fontStyle: "italic" }}>styled middle label</div> - custom middle label
• label={{ start:"I'm start label",middle: "middleLabel",end:<div style={{ fontSize: "1.3em", fontFamily: "fantasy", fontStyle: "italic" }}>big end label</div> }} start and middle label and custom end label
• label={{ 30: "label" }} - label 30 pixels relative to the start of the line
• label={{ 30%: "label" }} - label on the 30% of the total length from the start of the line
• label={{ 30%50: "label" }} - 30% of the total length, and 50 more pixels over the line

'start','middle',and 'end' labels have some predefined styles. custom labels (like 30%50: "label") will have the same style as middle label. if you dont like the style of 'start' and 'end' use 2% for start and 98% for end. make sure to stick between 0-100% in custom labels

you can combine all the different possible labels and can place as many as you want.

color defines color to the entire arrow. lineColor,headColor and tailColor will override color specifically for line,tail or head. examples:

• color="red" will change the color of the arrow to red(body and head).
• headColor="red" will change only the color of the head to red.
• tailColor="red" will change only the color of the tail to red.
• lineColor="red" will change only the color of the body to red.

strokeWidth defines the thickness of the entire arrow. headSize and tailSize defines how big will be the head or tail relative to the strokeWidth. examples:

• strokeWidth={15} will make the arrow more thick(body and head).
• headSize={15} will make the head of the arrow more thick(relative to strokeWidth as well).
• tailSize={15} will make arrow's tail thicker.

path can be one of: "smooth" | "grid" | "straight", and it controls the path arrow is drawn, exactly how their name suggest. examples:

• path={"grid"} will draw the line in sharp curves(90 degrees) like grid.

defines how much the lines curve. makes a difference only in path='smooth'. examples:

• curveness={false} will make the line straight without curves(exactly like path='straight').
• curveness={true} will choose default values of curveness.
• curveness={2} will make Xarrow extra curved.

defines where the line will break when path='grid'. value should be a number from 0 to 1.

examples:

• gridBreak={0.2} the line would break closer to start element(20% of the path instead of 50%).

can make the arrow dashed and can even animate. if true default values(for dashness) are chosen. if object is passed then default values are chosen except what passed. examples:

• dashness={true} will make the line of the arrow to be dashed.
• dashness={{ strokeLen: 10, nonStrokeLen: 15, animation: -2 }} will make a custom looking dashness.

showXarrow: show or not show Xarrow? (can be used to restart the drawing animation) showHead: show or not the arrow head? showTail: show or not the arrow tail?

• showXarrow={false} - will hide (unmount) Xarrow and his labels.
• showHead={false} - will hide the arrow head.

can animate the drawing of the arrow using svg animation. type: boolean|number. if true animation duration is 1s. if number is passed then animation duration is number's value in seconds. examples:

• animateDrawing will animate the drawing of the arrow in 1 second.
• animateDrawing={5} will animate the drawing of the arrow in 5 seconds.
• animateDrawing={0.1} will animate the drawing of the arrow in 100 milliseconds.

new feature! you can customize the svg edges (head or tail) of the arrow. you can use predefined svg by passing string,one of "arrow1" | "circle" | "heart"

simple usage:

headShape type:string

<xarrow headShape='circle'/>

<xarrow headShape='circle'
        arrowHeadProps={"fill": "transparent",
            "strokeWidth": "0.1",
            "stroke": "CornflowerBlue"}
/>

<xarrow headShape='heart'/>

you can import arrowShapes which is object contains all predefined svg shapes.

headShapeType = {
    svgElem: T
:
'circle' | 'ellipse' | 'line' | 'path' | 'polygon' | 'polyline' | 'rect';
svgProps ? : JSX.IntrinsicElements[T];
offsetForward ? : number;
}
;

headShape = {
    svgElem: 'path',
    svgProps: {d: `M 0 0 L 1 0.5 L 0 1 L 0.25 0.5 z`},
    offsetForward: 0.25
}

passing props

The xarrow is fully customizable, and you can pass props to any part of the component. if unlisted(unknown) property is passed to xarrow so by default it'll be passed down to divContainer.

passProps

you can pass properties to visible parts(body and head) of the arrow (such event handlers and much more). this supposed to be enough for most cases. examples:

• passProps= {{onClick: () => console.log("xarrow clicked!")}} - now the arrow will console log a message when clicked.
• passProps= {{cursor: "pointer"}} - now the cursor will change to pointer style when hovering over Xarrow.
• passProps= {{pointerEvents: "none"}} - now the user cannot interact with Xarrow via mouse events.

advanced customization

The properties below can be used to customize the arrow even farther:

arrowBodyProps, arrowHeadProps, SVGcanvasProps, divContainerProps

if you wish you can pass props specific part of the component.

• divContainerProps - the container which contains the SVG canvas, and the optional labels elements. It takes no place, and located where you normaly placed him in the elements tree(no offset). The SVGcanvas and the labels will be placed in a offset from this div.
• SVGcanvasProps - the svg canvas which contains arrow head and body.
• arrowBodyProps - the body of the arrow
• arrowHeadProps - the arrow head.

Note that arrowBody and arrowHead receives props of svg path element, SVGcanvas receives props of svg element, and divContainerProps of a div element.

examples:

• arrowHead = {onClick: () => console.log("head clicked!")} - now only the head will console log a message when clicked.

SVGcanvasStyle, divContainerStyle

if you wish to pass style to divContainer or SVGcanvas use SVGcanvasStyle,divContainerStyle and not SVGcanvasProps ,divContainerProps to not override existing style.

_extendSVGcanvas

will extend the svg canvas at all sides. can be useful if for some reason the arrow is cut though to small svg canvas( should be used in advanced custom arrows). example: _extendSVGcanvas = {30} - will extend svg canvas in all sides by 30 pixels.

_cpx1Offset,_cpy1Offset,_cpx2Offset,_cpy2Offset

now you can manipulate and offset the control points of the arrow. this way you can control how the line curves. check out the interactive codesandbox, set _debug to true and play with these properties.