SVG content can be interactive (i.e., responsive to user-initiated events) by utilizing the following features in the SVG language:
This chapter describes:
Related information can be found in other chapters:
The following aspects of SVG are affected by events:
The following table lists all of the events which are recognized and supported in SVG.
| Event Identifier {event-namespace, event-localname} |
Description | DOM3 event category | Animation event name |
|---|---|---|---|
| {"http://www.w3.org/2001/xml-events", "DOMFocusIn"} SVG 1.2 alias: {"http://www.w3.org/2001/xml-events", "focusin"} (see Notes below). |
Occurs when an element receives focus. | UIEvent | focusin |
| {"http://www.w3.org/2001/xml-events", "DOMFocusOut"} SVG 1.2 alias: {"http://www.w3.org/2001/xml-events", "focusout"} (see Notes below). |
Occurs when an element loses focus. | UIEvent | focusout |
| {"http://www.w3.org/2001/xml-events", "DOMActivate"} SVG 1.2 alias: {"http://www.w3.org/2001/xml-events", "activate"} (see Notes below). |
Occurs when an element is activated, for instance, thru a mouse click or a keypress. A numerical argument is provided to give an indication of the type of activation that occurs: 1 for a simple activation (e.g. a simple click or Enter), 2 for hyperactivation (for instance a double click or Shift Enter). | UIEvent | activate |
| {"http://www.w3.org/2001/xml-events", "click"} | Occurs when the pointing device button is clicked over
an element. A click is defined as a mousedown and mouseup
over the same screen location. The sequence of these events
is: mousedown, mouseup,
click. If multiple clicks occur at the same
screen location, the sequence repeats with the
detail attribute incrementing with each
repetition. |
MouseEvent | click |
| {"http://www.w3.org/2001/xml-events", "mousedown"} | Occurs when the pointing device button is pressed over an element. | MouseEvent | mousedown |
| {"http://www.w3.org/2001/xml-events", "mouseup"} | Occurs when the pointing device button is released over an element. | MouseEvent | mouseup |
| {"http://www.w3.org/2001/xml-events", "mouseover"} | Occurs when the pointing device is moved onto an element. | MouseEvent | mouseover |
| {"http://www.w3.org/2001/xml-events", "mousemove"} | Occurs when the pointing device is moved while it is over an element. | MouseEvent | mousemove |
| {"http://www.w3.org/2001/xml-events", "mouseout"} | Occurs when the pointing device is moved away from an element. | MouseEvent | mouseout |
| {"http://www.w3.org/2001/xml-events", "textInput"} | One or more characters have been entered. | TextEvent | none |
| {"http://www.w3.org/2001/xml-events", "keydown"} | A key is pressed down. (The normative definition of this event is the description in the DOM3 Events specification.) | KeyboardEvent | none |
| {"http://www.w3.org/2001/xml-events", "keyup"} | A key is released. (The normative definition of this event is the description in the DOM3 Events specification.) | KeyboardEvent | none |
| {"http://www.w3.org/2001/xml-events", "load"} Deprecated backwards-compatibility alias: {"http://www.w3.org/2001/xml-events", "SVGLoad"} (see Notes below). |
The event is triggered at the point at which the user agent has fully parsed the element and its descendants and is ready to act appropriately upon that element, such as being ready to render the element to the target device. Referenced external resources that are required must be loaded, parsed and ready to render before the event is triggered. Optional external resources are not required to be ready for the event to be triggered. | HTMLEvent | load |
|
{"http://www.w3.org/2001/xml-events", "resize"} Deprecated backwards-compatibility alias: SVGResize (see Notes below). |
Occurs when a document view is being resized. This event is only applicable to outermost 'svg' elements and is dispatched after the resize operation has taken place. The target of the event is the 'svg' element. | HTMLEvent | resize |
|
{"http://www.w3.org/2001/xml-events", "scroll"} Deprecated backwards-compatibility alias: SVGScroll (see Notes below). |
Occurs when a document view is being shifted along the X or Y or both axis, either through a direct user interaction or any change on the 'currentTranslate' property available on SVGSVGElement interface. This event is only applicable to outermost 'svg' elements and is dispatched after the shift modification has taken place. The target of the event is the 'svg' element. | HTMLEvent | scroll |
|
{"http://www.w3.org/2001/xml-events", "zoom"} Deprecated backwards-compatibility alias: {"http://www.w3.org/2001/xml-events", "SVGZoom"} (see Notes below). |
Occurs when the zoom level of a document view is being changed, either through a direct user interaction or any change to the 'currentScale' property available on SVGSVGElement interface. This event is only applicable to outermost 'svg' elements and is dispatched after the zoom level modification has taken place. The target of the event is the 'svg' element. | DOM3's SVG Events |
zoom |
| {"http://www.w3.org/2001/xml-events", "beginEvent"} | Occurs when an animation element begins. For details, see the description of Interface TimeEvent in the SMIL Animation specification. | DOM3's Timing Events | begin |
| {"http://www.w3.org/2001/xml-events", "endEvent"}. | Occurs when an animation element ends. For details, see the description of Interface TimeEvent in the SMIL Animation specification. | DOM3's Timing Events | end |
| {"http://www.w3.org/2001/xml-events", "repeatEvent"} | Occurs when an animation element repeats. It is raised each time the element repeats, after the first iteration. For details, see the description of Interface TimeEvent in the SMIL Animation specification. | DOM3's Timing Events | repeat |
| {"http://www.w3.org/2001/xml-events", "wheel"} | Occurs when a rotational input device has been activated. | UIEvent | none |
| {"http://www.w3.org/2000/svg", "connectionData"} | Occurs when data arrives. | none | none |
| {"http://www.w3.org/2000/svg", "preload"} | A load operation has begun. | none | none |
| {"http://www.w3.org/2000/svg", "loadprogress"} | Progress has occurred in loading a given resource. | none | none |
| {"http://www.w3.org/2000/svg", "postload"} | A load operation has completed. | none | none |
Notes:
In cases where the event name from SVG 1.1 differs from the DOM3 event name, but the SVG event name is more user-friendly (e.g., "focusin" is more user friendly than "DOMFocusIn"), the SVG 1.1 event name is not deprecated but instead retained as an alias for the DOM3 event name. Therefore:
begin="click".
Some exceptions to this rule is necessary for SVG 1.1 backwards compatibility
and to make it easier to integrate SVG with other W3C languages.
The following events use a different string than their localname as their event identifier for
SMIL timing attributes:
A SVGLoad event is dispatched only to the element to which the event applies; it is not dispatched to its ancestors. For example, if an 'image' element and its parent 'g' element both have event listeners for SVGLoad events, when the 'image' element has been loaded, only its event listener will be invoked. (The 'g' element's event listener will indeed get invoked, but the invocation will happen when the 'g' itself has been loaded.)
Details on the parameters passed to event listeners for the event types from DOM2 can be found in the DOM2 specification. For other event types, the parameters passed to event listeners are described elsewhere in this specification.
On user agents which support interactivity, it is common for authors to define SVG documents such that they are responsive to user interface events. Among the set of possible user events are pointer events, keyboard events, and document events.
In response to user interface (UI) events, the author might start an animation, perform a hyperlink to another Web page, highlight part of the document (e.g. change the color of the graphics elements which are under the pointer), initiate a "roll-over" (e.g., cause some previously hidden graphics elements to appear near the pointer) or launch a script which communicates with a remote database.
For all UI event-related features defined as part of the SVG language via XML Events or animation, the event model corresponds to the event bubbling model described in DOM2 [DOM2-EVBUBBLE]. The event capture model from DOM2 is not supported.
User interface events that occur because of user actions performed on a pointer device are called pointer events.
Many systems support pointer devices such as a mouse or trackball. On systems which use a mouse, pointer events consist of actions such as mouse movements and mouse clicks. On systems with a different pointer device, the pointing device often emulates the behavior of the mouse by providing a mechanism for equivalent user actions, such as a button to press which is equivalent to a mouse click.
For each pointer event, the SVG user agent determines the target element of a given pointer event. The target element is the topmost graphics element whose relevant graphical content is under the pointer at the time of the event. (See property 'pointer-events' for a description of how to determine whether an element's relevant graphical content is under the pointer, and thus in which circumstances that graphic element can be the target element for a pointer event.) When an element is not displayed (i.e., when the 'display' property on that element or one of its ancestors has a value of none), that element cannot be the target of pointer events.
The event is either initially dispatched to the target element, to one of the target element's ancestors, or not dispatched, depending on the following:
When event bubbling [DOM2-EVBUBBLE] is active, bubbling occurs up to all direct ancestors of the target element. Descendant elements receive events before their ancestors. Thus, if a 'path' element is a child of a 'g' element and they both have event listeners for click events, then the event will be dispatched to the 'path' element before the 'g' element.
After an event is initially dispatched to a particular element, the event will be passed to the appropriate event handlers (if any) for that element's ancestors (in the case of event bubbling) for further processing.
The processing order for user interface events is as follows:
Various elements in SVG create shadow content which can be the target of user interface events. The following is a list of elements that can create shadow content which can be the target of user interface events:
For these situations, user interface events within the shadow content participate in the processing of user interface events in the same manner as if the shadow content were part of the main document. In other words, if shadow content contains a graphics element that renders above other content at the current pointer location, then it represents the topmost graphics element and will receive the pointer events before other elements. In this case, the user interface events bubble up through the target's ancestors, and then across the document border into the referencing element, and then through the ancestors of the referencing element. This process continues as necessary if there are multiple levels of nested shadow trees.
In different circumstances, authors may want to control under what circumstances particular graphic elements can become the target of pointer events. For example, the author might want a given element to receive pointer events only when the pointer is over the stroked perimeter of a given shape. In other cases, the author might want a given element to ignore pointer events under all circumstances so that graphical elements underneath the given element will become the target of pointer events.
For example, suppose a circle with a 'stroke' of red (i.e., the outline is solid red) and a 'fill' of none (i.e., the interior is not painted) is rendered directly on top of a rectangle with a 'fill' of blue. The author might want the circle to be the target of pointer events only when the pointer is over the perimeter of the circle. When the pointer is over the interior of the circle, the author might want the underlying rectangle to be the target element of pointer events.
The 'pointer-events' property specifies under what circumstances a given graphics element can be the target element for a pointer event. It affects the circumstances under which the following are processed:
| Value: | visiblePainted | visibleFill | visibleStroke |
visible | painted | fill | stroke | all | none | inherit |
| Initial: | visiblePainted |
| Applies to: | graphics elements |
| Inherited: | yes |
| Percentages: | N/A |
| Media: | visual |
| Animatable: | yes |
For text elements, hit detection is performed on a character cell basis:
For raster images, hit detection is either performed on a whole-image basis (i.e., the rectangular area for the image is one of the determinants for whether the image receives the event) or on a per-pixel basic (i.e., the alpha values for pixels under the pointer help determine whether the image receives the event):
Note that for raster images, the values of properties 'fill-opacity', 'stroke-opacity', 'fill' and 'stroke' do not effect event processing.
Magnification represents a complete, uniform transformation on an SVG document fragment, where the magnify operation scales all graphical elements by the same amount. A magnify operation has the effect of a supplemental scale and translate transformation placed at the outermost level on the SVG document fragment (i.e., outside the 'svg' element).
Panning represents a translation (i.e., a shift) transformation on an SVG document fragment in response to a user interface action.
SVG user agents that operate in interaction-capable user environments are required to support the ability to magnify and pan.
The 'svg' element in an SVG document fragment has attribute zoomAndPan, which takes the possible values of disable and magnify, with the default being magnify.
If disable, the user agent shall disable any magnification and panning controls and not allow the user to magnify or pan on the given document fragment.
If magnify, in environments that support user interactivity, the user agent shall provide controls to allow the user to perform a "magnify" operation on the document fragment.
Animatable: no.
In many cases, such as text editing, the user is required to place focus on a particular element, ensuring that input events, such as keyboard input, are sent to that element.
All renderable elements can be focusable, including both container elements and graphics elements,. It is possible for a focusable container element to have focusable descendants.
Attribute definition:
System-dependent input facilities (e.g., the tab key on most desktop computers) should be supported to allow navigation between elements that can obtain focus (ie. elements for which the value of the focusable property evaluates to "true").
The document has the concept of a focus ring, which is the order in which elements obtain focus. By default the focus ring is obtained using document order. All focusable elements are part of the default focus ring. It is possible to override the default focus ring (see the Specifying navigation section below).
The SVG language supports a flattened notion of field navigation between focusable elements where it is possible to define field navigation between any two focusable elements defined within a given SVG document without regard to document hierarchy. For example:
<rect id="r1" focusable="true".../>
<g> id="g1" focusable="true">
<circle id="c1" focusable="true".../>
</g>
In the above example, it is possible to specify field-to-field navigation such that it is possible to navigate directly from any of the three elements. Thus, assuming a desktop computer which uses the tab key for field navigation, it is possible to specify focus navigation order such that the tab key takes the user from r1 to c1 to g1.
When navigating to an element that is not visible on the canvas the following rules apply:
display='none'. (An element which has display='none' is not focusable.)SVG's flattened notion of field navigation extends to referenced content and shadow trees as follows:
Focus navigation behaves as specified:
For stand-alone SVG documents, the User Agent must always have a currently focused object. If focus is not held by any elements in the document, the User Agent just give focus to the SVGDocument object.
For SVG documents which are referenced by a non-SVG host document (e.g., XHTML), the SVG document might participate within the host document's focus ring, which would allow direct navigation from an SVG focusable element onto a focusable element within the host document.
Navigation order can be specified using the focus attributes.
The allowed values for the focus attributes are either an IDREF or the string 'auto'. An IDREF value specifies the element that should receive focus if the corresponding navigation is triggered. The value 'auto' on focusNext and focusPrev effectively means the behavior is as if the attribute was not specified (navigation follows the rules specified above). The behaviour of 'auto' on the other focus attributes is left up to the User Agent.
When the user agent gives an element focus it receives a {"http://www.w3.org/2001/xml-events", "DOMFocusIn"} event which has the the new focused object as the event target and a {"http://www.w3.org/2001/xml-events", "DOMFocusOut"} event which has the previously focused object as the event target.
The SVGSVGElement interface has a setFocus(DOMObject object) method that puts the focus on the requested object. Calling setFocus with an element that is not focusable causes focus to stay on the currently focused object.
The SVGSVGElement interface has a moveFocus(short motionType) which moves current focus to a different object based on the value of motionType.
User agents which support pointer devices such as a mouse MUST allow users to put focus onto focusable elements. For example, it should be possible to click on a focusable element in order to give focus.
Empty text fields in SVG theoretically take up no space, but they have a point or zero-width line segment that represents the location of the empty text field. User agents should allow users with pointer devices to put focus into empty text fields by initiating a select action (e.g., a mouse click) at the location of the empty text field.
It is possible to change the field navigation order in script by catching the input event related to the navigation and cancelling the event.