The default semantics of a custom element is dependent upon the form in which it is instiantated:
+The default semantics of a custom element is dependent upon the form in which it is instantiated:
By default a custom tag has no special meaning at all. It represents its children.
-For example a custom tag, could be named taco-button but it does not express the semantics of a HTML button element simply due to its name. As instaniated a custom tag conveys a similar amount of semantics as a HTML div or span element. The addition of visual styling and scripted events to the taco-button could provide hints as to the semantics and expected interaction behaviours of the custom element for some users, but for the semantics to be formally expressed, developers must convey the role, states and properties of the element to browser APIs.
For example a custom tag, could be named taco-button, but it does not express the semantics of a HTML button element simply due to its name. As instantiated a custom tag conveys a similar amount of semantics as a HTML div or span element. The addition of visual styling and scripted events to the taco-button could provide hints as to the semantics and expected interaction behaviours of the custom element for some users, but for the semantics to be formally expressed, developers must convey the semantics using ARIA roles, states and properties.
<!-- taco-button represents a span with a fancy name -->
<taco-button></taco-button>
The addition of a tabindex attribute to the taco-button element provides interaction (the element is included in the focus order) and property/state semantics (it exposes information that it is focusable and if it currently has focus).
The addition of a tabindex attribute to the custom element provides interaction (the element is included in the focus order) and property/state semantics (it exposes information that it is focusable and if it currently has focus).
<!-- taco-button represents a focusable span with a fancy name -->
-<taco-button tabindex="0"></taco-button>
+<taco-button tabindex="0">Eat Me</taco-button>
The addition of a text label to the taco-button element provides an Accessible Name for the element.
<!-- taco-button represents a focusable span with a fancy name and a text label -->
-<taco-button tabindex="0">Eat Me</taco-button>
-or
-<taco-button tabindex="0" aria-label="Eat Me"></taco-button>
+<taco-button tabindex="0" aria-label="Eat Me">Eat Me</taco-button>
The addition of keyboard event handlers to the taco-button element provides the means for keyboard users to operate the control, but does not convey the presence of the functionality.
-The addition of in line event handlers are for demonstration purposes only. The event handlers could be added by the lifecycle callbacks imperatively, or maybe even not used at all.
+The addition of keyboard event handlers to the custom element element provides the means for keyboard users to operate the control, but does not convey the presence of the functionality.
+The addition of in line event handlers are for demonstration purposes only. The event handlers could be added by the lifecycle callbacks imperatively, or maybe even not used at all. This example demonstrates one method for developers to ensure that a custom control is operable for keyboard users and meets the WCAG 2.0 criteria "All functionality of the content is operable through a keyboard interface".
<!-- taco-button represents focusable span with a fancy name, a text label and button like event handling -->
<taco-button tabindex="0" onclick="alert('tasty eh?');"
onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};">Eat Me</taco-button>
The addition of an ARIA role="button" conveys the taco-button element's role semantics, which enables users to successfully interact with the control using the expected button interaction behaviours (pressing the space or enter keys to activate).
The addition of an ARIA role="button" conveys the custom element's role semantics, which enables users to successfully interact with the control using the expected button interaction behaviours (pressing the space or enter keys to activate).
<!-- taco-button represents a focusable button with a text label and button like event handling -->
<taco-button role="button" tabindex="0" onclick="alert('tasty eh?');"
onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};">Eat Me</taco-button>The developer may provide a disabled state for the custom element. This could be implemented by removing the tabindex attribute so the element is no longer included in the focus order and removing the functionality so that interacting with the element does nothing. Also the visual styling may also be modified to visually indicate it the element is disabled.
+<!-- grayed out non focusable taco-button with functionality removed, to indicate the button is in a disabled state -->
+<taco-button role="button" tabindex="0" onclick="alert('tasty eh?');"
+onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};">Eat Me</taco-button>Removing the focusability, functionality and modifying the style of the custom element does not unambiguously express that the custom element is in a disabled state. To unambiguously express the disabled state of the custom element add aria-disabled="true".
+<!-- taco-button represents a focusable button with a text label and button like event handling -->
+<taco-button role="button" tabindex="0" onclick="alert('tasty eh?');"
+onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};" aria-disabled="true">Eat Me</taco-button>By default a type extension inherits the semantics of the element type it extends.
-For example a type extension, could extend the HTML button element. As instaniated it would inherit the button element's name, role, states and properties, built in focus and keyboard interaction behaviours.
+<!-- taco-button represents a button with an accesssible name of "Eat Me!" --> -<button is="taco-button">Eat Me!</button>+Type Extension Example
+a type extension, could extend the HTML
+buttonelement. As instantiated it would inherit thebuttonelement's name, role, states and properties, built in focus and keyboard interaction behaviours.+<!-- tequila-button represents a button with an accessible name of "Drink Me!" --> +<button is="tequila-button">Drink Me!</button>+To implement the desired tequila-button feature, all that is required is the addition of an event handler. The rest of the semantics and interaction behaviour are provided by the browser as part of its implementation of the
+buttonelement.-<!-- tequila-button represents a button --> +<button is="tequila-button" onclick="alert('smooth!');">Drink Me!</button>To provide the desired taco-button feature, all that is required is the addition of an event handler. The rest of the semantics and interaction behaviour are provided by the browser as part of its implementation of the
-buttonelement.<!-- taco-button represents a button --> -<button is="taco-button" onclick="alert('tasty eh?');">Eat Me!</button>+To implement the disabled state on the tequila-button, all that is required is the addition of the HTML
+disabledattribute. The semantics, style and interaction behaviour are implemented by the browser.-<!-- tequila-button represents a button --> +<button is="tequila-button" onclick="alert('smooth!');" disabled>Drink Me!</button>TO DO
+Custom Element Semantics - Developer Advice
+As illustrated by the examples above. The simplest and most robust method to create custom elements that are usable and accessible is to implement custom elements as type extensions. This method provides a custom element with built in semantics and interaction behaviours which developers can use as a foundation.
+Use ARIA, where needed, to provide semantics for custom elements and follow the ARIA Design Patterns when implementing ARIA attributes and UI interaction behaviours. Ensure that custom tag or type extension custom elements meet the criteria listed in the Custom Control Accessible Development Checklist. Use ARIA in accordance with the Document conformance requirements for use of ARIA attributes in HTML.
+Further Reading for Developers
+
Alex Russell and his considerable forethought triggered a new wave of enthusiasm around the subject of behavior attachment and how it can be applied practically on the Web.
Dominic Cooney, Hajime Morrita, and Roland Steiner worked tirelessly to scope the problem within the confines of the Web platform and provided a solid foundation for this document.
+Steve Faulkner, The Paciello Group, for writing the content for the Custom Element Semantics section
The editor would also like to thank Alex Komoroske, Anne van Kesteren, Boris Zbarsky, Daniel Buchner, Edward O'Connor, Erik Arvidsson, Elliott Sprehn, Hayato Ito, Jonas Sicking, Olli Pettay, Rafael Weinstein, Scott Miles, Simon Pieters, Steve Orvell, Tab Atkins, and William Chen for their comments and contributions to this specification.