Excluding Elements from the Accessibility Tree

Certain elements in the DOM are not exposed via the accessibility API. The section Excluding Elements from the Accessibility Tree of the Core Accessibility API Mappings [[CORE-AAM]] outlines the general rules for excluding elements. One factor is whether host language semantics specify that the element should not be displayed.

The SVG language defines numerous elements that fit this criteria. Many SVG elements are never directly rendered to the screen, while others may or may not be rendered or displayed, depending on context or CSS styling. Elements which are neither perceivable nor interactive should not be included in the accessibility tree exposed to accessibility APIs. This section details the expected interpretation of SVG host language semantics.

Elements which are never directly rendered to screen, nor represented by an interactive region in a graphic, do not need a corresponding accessible object. User agents MUST NOT include any elements, or their descendant content, as an accessible object in the accessibility tree that are indicated as no accessible object created in the SVG Element Mapping Tables. User agents SHOULD also exclude any other element defined by past or future SVG specifications or modules that specifically indicate the element is never directly rendered.

For example, elements that represent filters, gradients, or gradient stops will never create an accessible object. Shape elements or image elements that are included in an SVG definitions section or as part of a pattern will also not have accessible objects, because the semantics of the ancestor defs or pattern element preclude that entire DOM subtree from being represented in the accessibility tree.

Elements that are excluded from the accessibility tree might still be used in the name and description computation of another element, as defined in the Name and Description section. Non-rendered elements may also be used as the templates for rendered element instances created by a use element, as described in the section on Use-Element Shadow Trees.

Although they are not directly included in the accessibility tree, animation and view elements can affect the accessible objects representing their target elements, as described under Special Processing Requiring Additional Computation.

In addition, SVG 1.1 [[SVG11]] defines the conditional processing attributes systemLanguage, requiredExtensions, and requiredFeatures. These may be used individually or in combination with the switch element to prevent content from being rendered under certain conditions, or to select between alternate versions of content.

SVG user agents MUST NOT expose to accessibility APIs any elements that are not rendered because of conditional processing attributes on that element or because of the position of that element within a switch construct. The switch element itself SHOULD be omitted as if it had a role of none or presentation.

The rendering of SVG elements is also affected by CSS styling properties, which may be specified using stylesheet rules, inline styles, presentation attributes, or animations. Regardless of how the style property is specified, the effect depends on the final computed value determined by the CSS cascade [[CSS-CASCADE-3]]. User agents MUST NOT expose to accessibility APIs any element that is not rendered because its computed style includes a value of none for the display property.

Other style properties can prevent an element, which is otherwise part of the rendering tree, from creating any visible representation in the rendered graphic. Such elements may still be interactive; they may receive keyboard focus or they may be associated with a region of the graphic that is responsive to pointer input events.

For the purpose of SVG, an element is considered hidden if it is neither visible, according to the computed value of the visibility property, nor interactive to pointer users. according to the pointer-events property. User agents SHOULD NOT expose to accessibility APIs any element that is hidden in this sense, unless the author explicitly overrides the hiding by setting the aria-hidden attribute to false.

In the case of container elements (such as g or svg), the element is not considered hidden if any of its descendent content is visible or can receive user events, regardless of the computed value of visibility on the element itself. Similarly, a use element may include visible or interactive component graphics, despite having style properties that would cause an individual shape element to be hidden. The use element MUST be considered visible or interactive if any elements within its shadow tree are visible or interactive. (The container or the use element may, however, still be considered presentational if it does not have any other reason to include it in the accessibility tree.) A shape element with markers is visible or interactive if any of its markers are visible or interactive.

An element that is currently positioned off-screen, or that is obscured by other elements, is not considered hidden. User agents should expose this state through other means, as described in the State and Property Mapping section of the Core Accessibility API Mappings [[CORE-AAM]].

Including Elements in the Accessibility Tree

Many SVG elements—although rendered to the screen—do not have an intrinsic semantic meaning. Instead, they represent components of the visual presentation of the document. To simplify the accessible representation of the document, these purely presentational elements should normally be omitted from the accessibility tree, unless the author explicitly provides semantic content.

However, any rendered SVG element may have semantic meaning. Authors indicate the significance of the element by including alternative text content or WAI-ARIA attributes. This section defines the rules for including normally-omitted elements in the accessibility tree.

The following graphical and container elements in the SVG namespace SHOULD NOT be included in the accessibility tree, except as described in this section:

• shape elements (circle, ellipse, line, path, polygon, polyline, rect)
• the use element
• the grouping (g) element
• the image element
• the mesh element
• text formatting elements (textPath, tspan)
• the foreignObject element

Although these elements are omitted from the accessibility tree, their child content is still processed, as if it was a direct child of the nearest ancestor node in the DOM tree that is included in the accessibility tree. In other words, the markup elements are treated as if they had a role of none or presentation.

For use elements, the elements and text in their associated shadow tree MUST be processed as if it was child content of the use element, following the conditions specified in processing requiring additional computation. This means that elements from the shadow tree can be included in the accessibility tree even if the use element itself has a (default or author-supplied) role of presentation.

SVG user agents MUST provide an accessible object in the accessibility tree for rendered SVG elements that meet any of the following criteria, unless they are excluded from the accessibility tree per the rules in Excluding Elements from the Accessibility Tree:

• It has at least one direct child ‘title’ element or ‘desc' element that is not empty after trimming whitespace. User agents MAY include elements with these child elements without checking for valid text content.
• It has a non-empty (after trimming whitespace) ‘aria-label’ attribute or ‘aria-roledescription’ attribute.
• It has an ‘aria-labelledby’ attribute or ‘aria-describedby’ attribute containing valid IDREF tokens. User agents MAY include elements with these attributes without checking for validity.
• It has a valid integer 'tabindex' attribute.
• The author has provided an allowed, non-abstract WAI-ARIA role other than none or presentation.
• It meets any of the criteria listed in the section Including Elements in the Accessibility Tree of the Core Accessibility API Mappings specification [[!CORE-AAM]].

Interactive elements are covered by the requirement regarding elements that may fire an Accessibility API event. Specifically, for SVG the following elements are interactive and MUST be included in the accessibility tree, without exception, regardless of whether they would otherwise be considered hidden or presentational:

• A rendered element (or instance of an element in a use-element shadow tree) with a positive integer value for the tabindex attribute, or which is focusable by default and has not been removed from the tab order with a negative integer tabindex attribute, which may receive keyboard focus and therefore keyboard input events.
• A rendered element (or instance of an element) that currently has keyboard focus (e.g., after being focused from a script), which may receive keyboard input events.

With regards to pointer events, which bubble up the DOM tree, the exact element that receives the event may not have semantic meaning (that is, it may still be presentational). However, the ability to receive pointer events overrides any exclusion based on the visibility: hidden style property.

The tabindex attribute and the pointer-events property have no impact on elements which are not rendered at all, because of the display: none property or because of host language semantics.