Class: SVGElement

Highcharts. SVGElement

new SVGElement()

The SVGElement prototype is a JavaScript wrapper for SVG elements used in the rendering layer of Highcharts. Combined with the Highcharts.SVGRenderer object, these prototypes allow freeform annotation in the charts or even in HTML pages without instanciating a chart. The SVGElement can also wrap HTML labels, when text or label elements are created with the useHTML parameter.

The SVGElement instances are created through factory functions on the Highcharts.SVGRenderer object, like rect, path, text, label, g and more.

See How to use the SVG Renderer for a comprehensive tutorial on how to draw SVG elements on a chart.

Members

element :Highcharts.SVGDOMElement|Highcharts.HTMLDOMElement

The primary DOM node. Each SVGElement instance wraps a main DOM node, but may also represent more nodes.

Type:

renderer :Highcharts.SVGRenderer

The renderer that the SVGElement belongs to.

Type:

Methods

add( [parent])

Add the element to the DOM. All elements must be added this way.

Parameters:
Name Type Argument Description
parent Highcharts.SVGElement <optional>

The parent item to add it to. If undefined, the element is added to the Highcharts.SVGRenderer.box.

Returns:
Highcharts.SVGElement .

Returns the SVGElement for chaining.

Try it

addClass(className [, replace])

Add a class name to an element.

Parameters:
Name Type Argument Default Description
className string

The new class name to add.

replace boolean <optional>
false

When true, the existing class name(s) will be overwritten with the new one. When false, the new one is added.

Returns:
Highcharts.SVGElement .

Return the SVG element for chainability.

align( [alignOptions] [, alignByTranslate] [, box] [, redraw])

Align the element relative to the chart or another box.

Parameters:
Name Type Argument Description
alignOptions Highcharts.AlignObject <optional>

The alignment options. The function can be called without this parameter in order to re-align an element after the box has been updated.

alignByTranslate boolean <optional>

Align element by translation.

box string | Highcharts.BBoxObject <optional>

The box to align to, needs a width and height. When the box is a string, it refers to an object in the Renderer. For example, when box is spacingBox, it refers to Renderer.spacingBox which holds width, height, x and y properties.

redraw boolean <optional>

Decide if SVGElement should be redrawn with new alignment or just change its attributes.

Returns:
Highcharts.SVGElement .

Returns the SVGElement for chaining.

animate(params [, options] [, complete])

Animate to given attributes or CSS properties.

Parameters:
Name Type Argument Description
params Highcharts.SVGAttributes

SVG attributes or CSS to animate.

options boolean | Partial.<Highcharts.AnimationOptionsObject> <optional>

Animation options.

complete function <optional>

Function to perform at the end of animation.

Returns:
Highcharts.SVGElement .

Returns the SVGElement for chaining.

Try it

attr(key)

Parameters:
Name Type Description
key string
Returns:

attr( [hash] [, val] [, complete] [, continueAnimation])

Apply native and custom attributes to the SVG elements.

In order to set the rotation center for rotation, set x and y to 0 and use translateX and translateY attributes to position the element instead.

Attributes frequently used in Highcharts are fill, stroke, stroke-width.

Parameters:
Name Type Argument Default Description
hash string | Highcharts.SVGAttributes <optional>

The native and custom SVG attributes.

val number | string | Highcharts.SVGPathArray <optional>

If the type of the first argument is string, the second can be a value, which will serve as a single attribute setter. If the first argument is a string and the second is undefined, the function serves as a getter and the current value of the property is returned.

complete function <optional>

A callback function to execute after setting the attributes. This makes the function compliant and interchangeable with the Highcharts.SVGElement#animate function.

continueAnimation boolean <optional>
true

Used internally when .attr is called as part of an animation step. Otherwise, calling .attr for an attribute will stop animation for that attribute.

Returns:
Highcharts.SVGElement .

If used as a setter, it returns the current Highcharts.SVGElement so the calls can be chained. If used as a getter, the current value of the attribute is returned.

Example
// Set multiple attributes
element.attr({
    stroke: 'red',
    fill: 'blue',
    x: 10,
    y: 10
});

// Set a single attribute
element.attr('stroke', 'red');

// Get an attribute
element.attr('stroke'); // => 'red'
Try it

clip( [clipElem])

Apply a clipping shape to this element.

Parameters:
Name Type Argument Description
clipElem Highcharts.SVGElement <optional>

The clipping shape. If skipped, the current clip is removed.

Returns:
Highcharts.SVGElement .

Returns the SVG element to allow chaining.

crisp(rect [, strokeWidth])

Calculate the coordinates needed for drawing a rectangle crisply and return the calculated attributes.

Parameters:
Name Type Argument Description
rect Highcharts.RectangleObject

Rectangle to crisp.

strokeWidth number <optional>

The stroke width to consider when computing crisp positioning. It can also be set directly on the rect parameter.

Returns:
Highcharts.RectangleObject .

The modified rectangle arguments.

css(styles)

Set styles for the element. In addition to CSS styles supported by native SVG and HTML elements, there are also some custom made for Highcharts, like width, ellipsis and textOverflow for SVG text elements.

Parameters:
Name Type Description
styles Highcharts.CSSObject

The new CSS styles.

Returns:
Highcharts.SVGElement .

Return the SVG element for chaining.

Try it

destroy()

Destroy the element and element wrapper and clear up the DOM and event hooks.

fadeIn( [animation])

A general fadeIn method.

Parameters:
Name Type Argument Description
animation boolean | Partial.<Highcharts.AnimationOptionsObject> <optional>

The animation options for the element fade.

Requires:
  • module:modules/drilldown

getBBox( [reload] [, rot])

Get the bounding box (width, height, x and y) for the element. Generally used to get rendered text size. Since this is called a lot in charts, the results are cached based on text properties, in order to save DOM traffic. The returned bounding box includes the rotation, so for example a single text line of rotation 90 will report a greater height, and a width corresponding to the line-height.

Parameters:
Name Type Argument Description
reload boolean <optional>

Skip the cache and get the updated DOM bounding box.

rot number <optional>

Override the element's rotation. This is internally used on axis labels with a value of 0 to find out what the bounding box would be have been if it were not rotated.

Returns:
Highcharts.BBoxObject .

The bounding box with x, y, width and height properties.

Try it

getStyle(prop)

Get the computed style. Only in styled mode.

Parameters:
Name Type Description
prop string

The property name to check for.

Returns:
string .

The current computed value.

Example
chart.series[0].points[0].graphic.getStyle('stroke-width'); // => '1px'

hasClass(className)

Check if an element has the given class name.

Parameters:
Name Type Description
className string

The class name to check for.

Returns:
boolean .

Whether the class name is found.

hide()

Hide the element, similar to setting the visibility attribute to hidden.

Returns:
Highcharts.SVGElement .

Returns the SVGElement for chaining.

init(renderer, nodeName)

Initialize the SVG element. This function only exists to make the initialization process overridable. It should not be called directly.

Parameters:
Name Type Description
renderer Highcharts.SVGRenderer

The SVGRenderer instance to initialize to.

nodeName string

The SVG node name.

on(eventType, handler)

Add an event listener. This is a simple setter that replaces the previous event of the same type added by this function, as opposed to the Highcharts#addEvent function.

Parameters:
Name Type Description
eventType string

The event type.

handler function

The handler callback.

Returns:
Highcharts.SVGElement .

The SVGElement for chaining.

Try it

removeClass(className)

Remove a class name from the element.

Parameters:
Name Type Description
className string | RegExp

The class name to remove.

Returns:
Highcharts.SVGElement .

Returns the SVG element for chainability.

setRadialReference(coordinates)

Set the coordinates needed to draw a consistent radial gradient across a shape regardless of positioning inside the chart. Used on pie slices to make all the slices have the same radial reference point.

Parameters:
Name Type Description
coordinates Array.<number>

The center reference. The format is [centerX, centerY, diameter] in pixels.

Returns:
Highcharts.SVGElement .

Returns the SVGElement for chaining.

setTextPath(path, textPathOptions)

Set a text path for a text or label element, allowing the text to flow along a path.

In order to unset the path for an existing element, call setTextPath with { enabled: false } as the second argument.

Parameters:
Name Type Description
path Highcharts.SVGElement | undefined

Path to follow. If undefined, it allows changing options for the existing path.

textPathOptions Highcharts.DataLabelsTextPathOptionsObject

Options.

Returns:
Highcharts.SVGElement .

Returns the SVGElement for chaining.

Try it

shadow( [shadowOptions])

Add a shadow to the element. In styled mode, this method is not used, instead use defs and filters.

Parameters:
Name Type Argument Description
shadowOptions boolean | Highcharts.ShadowOptionsObject <optional>

The shadow options. If true, the default options are applied. If false, the current shadow will be removed.

Returns:
Highcharts.SVGElement .

Returns the SVGElement for chaining.

Example
renderer.rect(10, 100, 100, 100)
    .attr({ fill: 'red' })
    .shadow(true);

show( [inherit])

Show the element after it has been hidden.

Parameters:
Name Type Argument Default Description
inherit boolean <optional>
true

Set the visibility attribute to inherit rather than visible. The difference is that an element with visibility="visible" will be visible even if the parent is hidden.

Returns:
Highcharts.SVGElement .

Returns the SVGElement for chaining.

strokeWidth()

Get the computed stroke width in pixel values. This is used extensively when drawing shapes to ensure the shapes are rendered crisp and positioned correctly relative to each other. Using shape-rendering: crispEdges leaves us less control over positioning, for example when we want to stack columns next to each other, or position things pixel-perfectly within the plot box.

The common pattern when placing a shape is:

  • Create the SVGElement and add it to the DOM. In styled mode, it will now receive a stroke width from the style sheet. In classic mode we will add the stroke-width attribute.
  • Read the computed elem.strokeWidth().
  • Place it based on the stroke width.
Returns:
number .

The stroke width in pixels. Even if the given stroke width (in CSS or by attributes) is based on em or other units, the pixel size is returned.

toFront()

Bring the element to the front. Alternatively, a new zIndex can be set.

Returns:
Highcharts.SVGElement .

Returns the SVGElement for chaining.

Try it

translate(x, y)

Move an object and its children by x and y values.

Parameters:
Name Type Description
x number

The x value.

y number

The y value.

Returns:
Highcharts.SVGElement .

Translated element.