[contents] [checklist]


Client-side Scripting Techniques for WCAG 2.0

W3C Working Draft 30 June 2005

This version:
Latest version:
Previous version:
Matt May, W3C
Becky Gibson, IBM


This document provides information to Web content developers who wish to satisfy the success criteria of "Web Content Accessibility Guidelines 2.0" [WCAG20] (currently a W3C Working Draft). The techniques in this document are specific to ECMAScript although some techniques contain Cascading Style Sheet [CSS1] and Hypertext Markup Language content [HTML4], [XHTML1] solutions. Use of the illustrative techniques provided in this document may make it more likely for Web content to demonstrate conformance to WCAG 2.0 success criteria (by passing the relevant tests in the WCAG 2.0 test suite - to be developed) than if these illustrative techniques are not used.

There may be other techniques besides those provided in this document that may be used to demonstrate conformance to WCAG 2.0; in that case, it is encouraged to submit those techniques to the WCAG WG for consideration for inclusion in this document, so that the set of techniques maintained by the WCAG WG is as comprehensive as possible. Deprecated examples illustrate techniques that the Working Group no longer recommends, but may be applicable in some cases. Some techniques may have errors that we have been unable to correct since the 19 November 2004 Working Draft since the WCAG WG has been focusing on guidelines and success criterion for this set of Working Drafts.

This document is part of a series of documents published by the W3C Web Accessibility Initiative (WAI) to support WCAG 2.0.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This version of Client-side Scripting techniques has not significantly changed since the 19 November 2004 Working Draft. The Web Content Accessibility Guidelines Working Group (WCAG WG) has focused on addressing issues related to Guidelines and Success Criteria. This publication demonstrates how the different documents may link to each other. As the focus of the WCAG WG returns to techniques and test suites, the structure and presentation of the techniques documents will likely change to reflect the relationships between Guidelines, Techniques, and testing documents. In future revisions, we expect to distinguish between techniques required for conformance versus those that are optional. Please refer to "Client Side Scripting Techniques Issues" for a list of open issues related to this Working Draft.for a list of open issues related to this Working Draft.

Please send comments about this document to public-comments-wcag20@w3.org. The archives for the public comments list are publicly available. Archives of the WCAG WG mailing list are also publicly available.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress. The WCAG WG intends to publish this as a Working Group Note at the time that WCAG 2.0 becomes a Recommendation.

This document has been produced as part of the W3C Web Accessibility Initiative (WAI). The goals of the WCAG WG are discussed in the Working Group charter. The WCAG WG is part of the WAI Technical Activity.

Table of Contents


This is the Client-side Scripting Techniques for Web Content Accessibility Guidelines 2.0 [WCAG20] This document describes techniques for authoring accessible ECMAScript-based scripts. ECMAScript is defined by the ECMA-262 specification [ECMA262]. This document is intended to help authors of Web content who wish to claim conformance to WCAG 2.0. While the techniques in this document should increase overall accessibility of Web resources, they are not a comprehensive resource for script accessibility.

WCAG 2.0 does not provide an explicit baseline of technologies that must be adhered to when authoring Web content. This is a different approach from WCAG 1.0 [WCAG10] Checkpoint 6.3 "Ensure that pages are usable when scripts, applets, or other programmatic objects are turned off or not supported. If this is not possible, provide equivalent information on an alternative accessible page." Thus, the need for equivalents for scripted content depends on a number of factors including user agent and assistive technology support and the Web site audience. For additional information related to choosing an appropriate baseline, refer to [@@ link to resource discussing the issues considerations in choosing an appropriate baseline]. In addition, all authors must assume that persons with disabilities will access the site. Thus, any scripting used must be accessible.

Authors should consider whether they genuinely need to use script in certain situations, or whether they can augment an HTML-based solution with script so that users with script turned off may still use the document. It is always important to adopt the least-restrictive set of technologies possible when authoring Web content. However, it is not always possible to build more complicated Web sites or Web applications without the use of some client side scripting. The UAAG 1.0 [UAAG10] provides guidance on browser integration of scripting languages in Guideline 6, Implement interoperable application programming interfaces . Authors using scripts must do so in a manner such that the scripts can be run in user agents conforming to UAAG 1.0 Guideline 6.

At the time of publication, it is assumed that user agents and assistive technologies that support the techniques in this document are generally available in most common languages found on the Web. However, the use of scripting techniques must be based on the expected audience of the Web content. The audience assumptions may be dictated by policy in a given country, organization or governing body. The Web author is responsible for understanding the policies in affect for the content when it is published and writing to that level of support.

Note: Techniques in this document are known to contain errors that we have been unable to correct since the 19 November 2004 Working Draft since the WCAG WG has been focusing on guidelines and success criterion for this set of Working Drafts. The purpose of this document is to receive feedback about the content of the techniques to ensure that future drafts are more accurate and useful. These techniques should not be implemented by people attempting to attain WCAG conformance at this time.

Future Work

The WCAG 2.0 Conformance Requirements section has been updated to help authors specify conformance with respect to a set of baseline technologies. Future versions of this document will contain additional techniques to demonstrate the accessible use of scripting when it is included in the baseline. It has been proposed that scripting techniques be divided into three categories:

  1. No Script - Best practices for authoring content that will work properly with or without support for client side scripting.

  2. Scripting Enhancements - Client side scripting techniques that enhance the accessibility or usability of a site for persons with disabilities. These techniques assume that scripting is supported and turned on in the user agents and assistive technologies used by the target audience.

  3. Accessible Scripting - Best practices for writing scripts that are accessible to user agents which conform to Guideline 6 of UAAG. These techniques do not necessarily improve the accessibility of the Web content, but they may increase the usability or performance without harming access by persons with disabilities.

An author using techniques from the Scripting Enhancement and Accessible Scripting categories must be certain that the expected audience has access to user agents and assistive technologies that support scripting. When possible, user agent and assistive technology support for each technique will be noted.

The WCAG WG welcomes comments on these proposed categories and Submissions of additional techniques.

Editorial Note: As work on the technology-specific techniques documents and checklists progresses, we expect to clearly distinguish between techniques required for conformance versus those that are optional. That distinction is not made in this Working Draft. The issue is captured as Issue #772 -"How do we make it clear that there are some techniques that are sufficient and some that are optional?"

1. Forms

Editorial Note: The WCAG WG anticipates that a separate techniques document will focus on metadata, semantic web issues, and RDF and will be referenced from this section.

1.1 Form URIs

This technique relates to the following sections of the guidelines:


Avoid javascript: URIs for form actions.

Setting the action attribute in a form to a javascript: URI causes non-script-capable browsers to fail silently.

Deprecated Example:

This example code shows a problematic use of the javascript: URI:

<form action="javascript:submitmyform()">

Deprecated Example:

Another common error is to point the form's action to "#" (the top of the current document), while using the onsubmit event. This causes users of non-script-capable browsers to become confused, as their repeated activation of the submit button does nothing.

<form action="#" onsubmit="submitmyform()">


The correct method for firing an ECMAScript function when a form is submitted is to use the onsubmit event. The checkFormFields() function would return true if there are form errors, stopping the submission of the form:

<form action="submit.php" onsubmit="return checkFormFields();">

1.2 Images as submit buttons

This technique relates to the following sections of the guidelines:


Avoid using images with onclick="form.submit()" as submit buttons.

A submit button is a submit button, and an image is an image. There is no need to mix the two. However, it is very common to see the following code, which leaves users of screen readers and people who can't use a mouse completely unable to submit their form:

Deprecated Example:

<img src="submit.gif" alt="Submit this form" onclick="submitmyform()">


The example below shows how to create an image-based submit button that is compatible with assistive technology:

<input type="image" name="submit" src="submit.gif" alt="Submit this form">

2. Links

2.1 javascript: URIs

This technique relates to the following sections of the guidelines:


Avoid javascript: URIs. Attach events using DOM event attributes.

The javascript: URI space should not be used. All ECMAScript should be designed to degrade gracefully when script is not supported, and javascript: URIs necessarily break that graceful degradation.

Editorial Note: This is being discussed in the WG presently. One issue is whether, if JavaScript is assumed to exist in the client, it is necessary to restrict javascript: URIs. On the other hand, the javascript: namespace has referentiality problems, and in many cases, users can enjoy backward-compatibility without any undue burden on the author. (See bug 1073 for more detail.)

Deprecated Example:

Code such as the example below locks many users out of important portions of the site:

<a href="javascript:window.open('register.php')">click here</a> to register.


It is better in general to use the DOM events (onactivate, onclick, onkeypress, etc.) to call script functions, but leave a real http: URI in the link for non-script-capable browsers. In rare cases, it may be necessary to create a second page that duplicates the functionality of the page called by the script, but most of the time it is sufficient to point users to the same target page that is called by the script.

<a href="register.php" target="registerwindow"
 onclick="window.open('',this.target);">register here</a>

2.2 Dynamic content generation

This technique relates to the following sections of the guidelines:


Avoid document.write() and innerHTML().

Assistive technologies such as screen readers rely on the Document Object Model (DOM) to interpret the semantics in HTML for a different modality. Given this, the document.write() and innerHTML() methods can render content invalid (and inaccessible via DOM) after the fact.

Deprecated Example:

This deprecated example shows a script that inserts a header, a paragraph (which is unterminated, and thus invalid), and a list (again, invalid) into a given document.

function fillContent() {
	document.write("<h1>Welcome to my site</h1>");
	document.write("<p>Lorem ipsum dolor sit amet");
	document.menu.innerHTML = "<ul><li><a href="foo.html">foo</a>";


The following code sample does the same as the example above, but produces valid code which appears in the HTML document's DOM tree:

function fillContent() {
	// parentelem is a specified element in the DOM
	var header = document.createElement("h1");
	header.insertText("Welcome to my site");
	var para = document.createElement("p");
	para.insertText("Lorem ipsum dolor sit amet");
	var list = document.createElement("ul");
	itemone = document.createElement("li");
	itemonelink = document.createElement("a");

Editorial Note: Two issues have been raised with this example what happens to XSL on server-side and how does this effect XPointers (and RDF-based accessibility).

2.3 Changing focus

This technique relates to the following sections of the guidelines:


Avoid changing focus on the user.

This includes such things as creating new windows, which are covered elsewhere in the techniques documents. But it also includes the focus() function in ECMAScript. Setting focus changes the cursor position in a screen reader, which is akin to moving the mouse without the author's position. Users are disoriented, and in certain cases, may not be able to get to certain parts of the document.

Editorial Note: tabindex? onblur/onfocus events?


Editorial Note: This technique is to be adapted in a later draft. We do not yet have a good code example for this, since it is related more to a chain reaction of sorts.


2.4 Device-independent events

This technique relates to the following sections of the guidelines:


Avoid device-dependent events, or use both keyboard- and mouse-based functions.


<p><a href="menu.php" onclick="checkForCookie()" 
onkeypress="checkForCookie()">main menu</a></p>

2.5 The onactivate event

This technique relates to the following sections of the guidelines:


Use the onactivate event in place of onclick.

With onactivate, keyboard users can trigger scripts by hitting enter on a target they've tabbed to, while mouse users can click on the same links.


Editorial Note: The technique below is to be adapted. While onactivate is invalid HTML, it is possible to attach an onactivate event to an element in the script block. However, this is a part of a broader strategy for techniques which will be explored in a later draft.

<p><a href="menu.php" onactivate="checkForCookie()">main menu</a></p>

2.6 Dynamic HTML menus


This task will describe an accessible method for interactive menus, also known as "DHTML menus".

Editorial Note: This technique is a placeholder. The editor will research methods for creating menus using script and CSS, have them tested against our requirements, and publish example code here.

3. References

"Cascading Style Sheets, level 1," B. Bos, H. Wium Lie, eds., W3C Recommendation 17 Dec 1996, revised 11 Jan 1999. Available at http://www.w3.org/TR/REC-CSS1.
"Cascading Style Sheets, level 2," B. Bos, H. Wium Lie, C. Lilley, and I. Jacobs, eds., W3C Recommendation 12 May 1998. Available at http://www.w3.org/TR/REC-CSS2.
"Standard ECMA-262: ECMAScript Language Specification, 3rd edition," December 1999. Available at: http://www.ecma-international.org/publications/standards/Ecma-262.htm
"HTML 4.01 Specification," D. Raggett, A. Le Hors, I. Jacobs, eds., W3C Recommendation 24 December 1999. Available at http://www.w3.org/TR/html401/
"User Agent Accessibility Guidelines 1.0," I. Jacobs, J. Gunderson, E. Hansen eds., W3C Recommendation 17 December 2002. Available at http://www.w3.org/TR/UAAG10/.
"Web Content Accessibility Guidelines 1.0," W. Chisholm, G. Vanderheiden, and I. Jacobs, eds., W3C Recommendation 5 May 1999. Available at http://www.w3.org/TR/WCAG10/
"Web Content Accessibility Guidelines 2.0," B. Caldwell, W. Chisholm, J. White, and G. Vanderheiden, eds., W3C Working Draft 30 June 2005. This W3C Working Draft is available at http://www.w3.org/TR/2005/WD-WCAG20-20050630. The latest version of WCAG 2.0 is available at http://www.w3.org/TR/WCAG20/
"XHTML 1.0 The Extensible HyperText Markup Language (Second Edition)," S. Pemberton, et al., W3C Recommendation 26 January 2000, revised 1 August 2002. Available at: http://www.w3.org/TR/xhtml1/.