jQuery

jQuery

Source:
See:

Members

(static) ariaFix :Object.<String>

Source:

A map of unprefixed WAI-ARIA attributes that should be converted before being normalised (see jQuery.normaliseAria).

Type:
  • Object.<String>
Example

Correcting a common typo

$.ariaFix.budy = "busy";
$.normaliseAria("budy");      // -> "aria-busy"
$.normaliseAria("aria-budy"); // -> "aria-busy"

(static) ariaHooks :Object.<ARIA_hook>

Source:

A collection of hooks that change the behaviour of attributes being set, retrieved, checked or removed (called set, get, has, unset - see ARIA_hook for full details). The name of the hook is always the un-prefixed WAI-ARIA attribute in lower case after any mapping has occurred (see jQuery.ariaFix). If you are ever in doubt, the easiest way to know the key is to slice the normalised value: $.normaliseAria(WAI-ARIA_ATTRIBUTE).slice(5) (see jQuery.normaliseAria for more information).

Do not use these functions to set different WAI-ARIA attributes without setting the one being passed to the aria method; for example: do not create a set for "attribute1" that sets "attribute2" instead - unless you add the same conversion to has, get will not be triggered. Instead, use jQuery.ariaFix to convert the attribute name.

jQuery#aria, jQuery#ariaRef, jQuery#ariaState, jQuery#removeAria, jQuery#removeAriaRef and jQuery#removeAriaState all run through these hooks (if they exist) and these hooks replace the functionality of manipulating or checking the attributes after any conversion process has occurred within the method itself.

Type:
Example
// aria-level should be an integer greater than or equal to 1 so the getter
// should return an integer.
$.ariaHooks.level = {
    set: function (element, value) {
        var intVal = Math.max(1, Math.floor(value));
        if (!isNaN(intVal)) {
            element.setAttribute("aria-level", intVal)
        }
    },
    get: function (element) {
        var value = element.getAttribute("aria-level");
        var intVal = (Math.max(1, Math.floor(value));
        return (value === null || isNaN(intVal))
            ? undefined
            : intVal;
    }
};

Methods

(static) normaliseAria(name) → {String}

Source:
Properties:
Name Type Description
cache Object.<String>

The cache of requests to responses.

Normalises a WAI-ARIA attribute name so that it's always lower case and always stars with aria-. If the unprefixed value appears in jQuery.ariaFix then the mapped version is used before being prefixed.

The results of this function are cached to help reduce processing. This is exposed as jQuery.normaliseAria.cache if needed but there is no need to clear the cache after modifying jQuery.ariaFix - changes are automatically considered in the caching process.

This function is aliased as jQuery.normalizeAria.

Examples

Basic example

$.normaliseAria("label");      // -> "aria-label"
$.normaliseAria("LABEL");      // -> "aria-label"
$.normaliseAria("aria-label"); // -> "aria-label"
$.normaliseAria();             // -> "aria-"

Alias

$.normalizeAria("label");      // -> "aria-label"
$.normalizeAria("LABEL");      // -> "aria-label"
$.normalizeAria("aria-label"); // -> "aria-label"
$.normalizeAria();             // -> "aria-"

Mapped attribute

// $.ariaFix = {labeledby: "labelledby"}
$.normaliseAria("labeledby");      // -> "aria-labelledby"
$.normaliseAria("LABELEDBY");      // -> "aria-labelledby"
$.normaliseAria("aria-labeledby"); // -> "aria-labelledby"

The cache

$.normaliseAria("busy");    // -> "aria-busy"
$.normaliseAria("busy");    // -> "aria-busy" (from cache)
$.normaliseAria("checked"); // -> "aria-checked"
$.normaliseAria("busy");    // -> "aria-busy" (from cache)
$.normaliseAria.cache;
// -> {"busy": "aria-busy", "checked": "aria-checked"}
Parameters:
Name Type Description
name String

Attribute name to normalise.
Returns:

Normalised attribute name.

Type
String

(static) normalizeAria(name) → {String}

Source:
Properties:
Name Type Description
cache Object.<String>

The cache of requests to responses.

Alias of jQuery.normaliseAria

Parameters:
Name Type Description
name String

Attribute name to normalise.
Returns:

Normalised attribute name.

Type
String

addRole(role) → {jQuery}

Source:

Adds a role to a collection of elements. The role will not be added if it's empty ("" or undefined), if the function response is empty or if the element already has that role. In that way it's similar to jQuery#addClass.

Examples

Adding a role

// Markup is:
// <div class="one" role="presentation"></div>
// <div class="one"></div>

$(".one").addRole("alert"); // -> jQuery(<div>, <div>)

// Now markup is:
// <div class="one" role="presentation alert"></div>
// <div class="one" role="alert"></div>

Adding a role with a function

// Markup is:
// <div class="one" role="presentation"></div>

$(".one").addRole(function (index, current) {
    return "alert combobox";
});

// Now markup is:
// <div class="one" role="presentation alert combobox"></div>
Parameters:
Name Type Description
role Attribute_Callback | String

Role(s) to add to the matching elements or function to generate the role(s) to add.
Returns:

jQuery object representing the matching elements.

Type
jQuery

aria(property, valueopt) → {jQuery|String|undefined}

Source:

Gets or sets WAI-ARIA properties. The properties will not be modified any more than they need to be (unlike jQuery#ariaRef or jQuery#ariaState which will interpret the values).

To set WAI-ARIA properties, pass either a property/value pair of arguments or an object containing those pairs. When this is done, the attributes are set on all elements in the collection and the jQuery object is returned to allow for chaining. If value is a function and returns undefined (or nothing) then no action is taken for that element. This can be useful for selectively setting values only when certain criteria are met.

To get WAI-ARIA properties, only pass the property that you want to get. If there is no matching property, undefined is returned. All properties are normalised (see jQuery.normaliseAria).

Examples

Setting WAI-ARIA attribute(s)

$("#element").aria("aria-label", "test");
// or
$("#element").aria("label", "test");
// or
$("#element").aria({
    "aria-label": "test"
});
// or
$("#element").aria({
    label: "test"
});
// All of these set aria-label="test" on all matching elements and return a
// jQuery object representing "#element"

Setting WAI-ARIA attribute(s) with a function

$("#element").aria("label", function (i, attr) {
    return this.id + "__" + i + "__" + attr;
});
// or
$("#element").aria({
    label: function (i, attr) {
        return this.id + "__" + i + "__" + attr;
    }
});
// Both of these set aria-label="element__0__undefined" on all matching
// elements and return a jQuery object representing "#element"

Getting a WAI-ARIA attribute

// Markup is:
// <div id="element" aria-label="test"></div>
$("#element").aria("label");   // -> "test"
$("#element").aria("checked"); // -> undefined
// If "#element" matches multiple elements, the attributes from the first
// element are returned.

Setting with aria methods

// Markup is:
// <div class="one"></div>
// <div class="two"></div>
// <div class="three"</div>

var settings = {
    busy: 0,
    controls: ".one",
    label: "lorem ipsum"
};

$(".one").aria(settings);
$(".two").ariaRef(settings);
$(".three").ariaState(settings);

// Now markup is:
// <div class="one"
//     aria-busy="0"
//     aria-controls=".one"
//     aria-label="lorem ipsum"
//     id="anonymous0"></div>
// <div class="two"
//     aria-controls="anonymous0"></div>
// <div class="three"
//     aria-busy="false"
//     aria-controls="true"
//     aria-label="true"></div>

Getting with aria methods

// Markup is:
// <div id="test" aria-flowto="false"></div>
// <div id="false"></div>

$("#test").aria("flowto");      // -> "false"
$("#test").ariaRef("flowto");   // -> jQuery(<div id="false">)
$("#test").ariaState("flowto"); // -> false
Parameters:
Name Type Attributes Description
property Object | String

Either the properties to set in key/value pairs or the name of the property to get/set.
value Attribute_Callback | Boolean | Number | String <optional>

The value of the property to set.
Returns:

Either the jQuery object (after setting) or a string or undefined (after getting)

Type
jQuery | String | undefined

ariaFocusable(state) → {jQuery}

Source:

Sets whether or not the matching elements are focusable. Strings, numbers and booleans are understood as state - see jQuery#ariaState for full details as the algorythm is the same.

Be aware this this function will only modify the matching elements, it will not check any parents or modify any other elements that could affect the focusability of the element.

Examples

Setting focusability

// Markup is
// <div id="one"></div>
// <div id="two"></div>

$("#one").ariaFocusable(false); // -> jQuery(<div id="one">)
$("#two").ariaFocusable(true);  // -> jQuery(<div id="two">)

// Now markup is
// <div id="one" tabindex="0"></div>
// <div id="two" tabindex="-1"></div>

Limitations of the function

// Markup is
// <div id="one" tabindex="-1">
//     <div id="two" disabled></div>
// </div>

$("#two").ariaFocusable(true); // -> jQuery(<div id="two">)

// Now markup is
// <div id="one" tabindex="-1">
//     <div id="two" disabled tabindex="0"></div>
// </div>
Parameters:
Name Type Description
state Attribute_Callback | Boolean | Number | String

State to set.
Returns:

jQuery object representing the affected element(s).

Type
jQuery

ariaRef(property, valueopt) → {jQuery}

Source:

Gets or sets a WAI-ARIA reference. This is functionally identical to jQuery#aria with the main difference being that an element may be passed as the value when setting and that a jQuery object is returned when getting.

Because WAI-ARIA references work with IDs, IDs are worked out using jQuery#identify. Be aware that any string passed to jQuery#ariaRef will be treated like a CSS selector and looked up with the results being used to set the property. If you already have the ID and wish to set it without the lookup, use jQuery#aria.

If value is a function then the resulting value is identified. This can be particularly useful for performing DOM traversal to find the reference (see examples below). As with jQuery#aria, if the value function returns nothing or returns undefined then no action is taken.

When accessing the attribute using this function, a jQuery object representing the reference is returned. If there are multiple elements in the collection, only the reference for the first element is returned. To get the value of the attribute rather than the element, use jQuery#aria.

Examples

Setting references

// Markup is:
// <h1>Heading</h1>
// <div class="one">
//     Lorem ipsum dolor sit amet ...
// </div>

$(".one").ariaRef("labelledby", $("h1"));
// or
$(".one").ariaRef("labelledby", "h1");
// or
$(".one").ariaRef("labelledby", $("h1")[0]);
// or
$(".one").ariaRef({
    labelledby: $("h1") // or "h1" or $("h1")[0]
});
// Each of these return a jQuery object representing ".one"

// Now markup is:
// <h1 id="anonymous0">Heading</h1>
// <div class="one" aria-labelledby="anonymous0">
//     Lorem ipsum dolor sit amet ...
// </div>

Setting references with a function

// Markup is:
// <div class="js-collapse">
//     <div class="js-collapse-content">
//         Lorem ipsum dolor sit amet ...
//     </div>
//     <button class="js-collapse-toggle">
//         Toggle
//     </button>
// </div>

$(".js-collapse-toggle").ariaRef("controls", function (i, attr) {

    return $(this)
        .closest(".js-collapse")
        .find(".js-collapse-content");

});

// Now markup is:
// <div class="js-collapse">
//     <div class="js-collapse-content" id="anonymous0">
//         Lorem ipsum dolor sit amet ...
//     </div>
//     <button class="js-collapse-toggle" aria-controls="anonymous0">
//         Toggle
//     </button>
// </div>

Getting a reference

// Markup is:
// <h1 id="anonymous0">Heading</h1>
// <div class="one" aria-labelledby="anonymous0">
//     Lorem ipsum dolor sit amet ...
// </div>

$(".one").ariaRef("labelledby"); // -> $(<h1>)
$(".one").ariaRef("controls");   // -> $()

Value is treated like a CSS selector

// Markup is:
// <button id="button"></button>
// <div id="section"></div>
// <section></section>

$("#button").ariaRef("controls", "section");

// Now markup is:
// <button id="button" aria-controls="anonymous0"></button>
// <div id="section"></div>
// <section id="anonymous0"></section>
Parameters:
Name Type Attributes Description
property Object | String

Either the properties to set in key/value pairs or the name of the property to set.
value Attribute_Callback | jQuery_param <optional>

Reference to set.
Returns:

jQuery object representing either the elements that were modified (when setting) or the referenced element(s) (when getting - may be an empty jQuery object).

Type
jQuery

ariaState(property, valueopt) → {ARIA_state|jQuery}

Source:

Sets or gets the WAI-ARIA state of the collection.

When setting the state, false, "false" (any case), 0 and "0" will be considered false. All other values will be considered true except for "mixed" (any case) which will set the state to "mixed". The differs from jQuery#aria which will simply set the attribute(s) without converting the value.

After setting the state(s), a jQuery object representing the affected elements is returned. The state for the first matching element is returned when getting.

All attributes are normalised - see jQuery.normaliseAria for full details.

Examples

Getting state

// Markup is:
// <div id="one" aria-busy="true" aria-checked="mixed"></div>

$("#one").ariaState("busy");    // -> true
$("#one").ariaState("checked"); // -> "mixed"
$("#one").ariaState("hidden");  // -> undefined

Setting state

// Each of these will set the state to false:
$("#one").ariaState("busy", "false");
$("#one").ariaState("busy", "FALSE");
$("#one").ariaState("busy", false);
$("#one").ariaState("busy", 0);
$("#one").ariaState("busy", "0");

// Each of these will set the state to "mixed":
$("#one").ariaState("checked", "mixed");
$("#one").ariaState("checked", "MIXED");

// Each of these will set the state to true
$("#one").ariaState("busy", "true");
$("#one").ariaState("busy", "TRUE");
$("#one").ariaState("busy", true);
$("#one").ariaState("busy", 1);
$("#one").ariaState("busy", "1");
// WARNING: these also set the state to true
$("#one").ariaState("busy", {});
$("#one").ariaState("busy", null);
$("#one").ariaState("busy", "nothing");
$("#one").ariaState("busy", "");
$("#one").ariaState("busy", -1);

// Each example returns a jQuery object representing "#one" and an object
// can be passed as parameters as well:
$("#one").ariaState({
    busy: true
});

Setting state with a function

// Markup is:
// <div class="checkbox"></div>
// <input type="checkbox" checked>

$(".checkbox").ariaState("checked", function (i, attr) {

    return $(this)
        .next("input[type=\"checkbox\"]")
        .prop("checked");

});

// Now markup is:
// <div class="checkbox" aria-checked="true"></div>
// <input type="checkbox" checked>
Parameters:
Name Type Attributes Description
property Object | String

Either a key/value combination properties to set or the name of the WAI-ARIA state to set.
value Attribute_Callback | Boolean | Number | String <optional>

Value of the attribute.
Returns:

Either the jQuery object representing the modified elements (setting) or the state of the first matching element.

Type
ARIA_state | jQuery

identify() → {String|undefined}

Source:

Identifies the first element in the collection by getting its ID. If the element doesn't have an ID attribute, a unique on is generated and assigned before being returned. If the collection does not have a first element then undefined is returned.

IDs are a concatenation of "anonymous" and a hidden counter that is increased each time. If the ID already exists on the page, that ID is skipped and not assigned to a second element.

Examples

Identifying elements

// Markup is
// <div class="one"></div>
// <span class="one"></span>

$(".one").identify(); // -> "anonymous0"

// Now markup is:
// <div class="one" id="anonymous0"></div>
// <span class="one"></span>
// Running $(".one").identify(); again would not change the markup.

Existing IDs are not duplicated

// Markup is:
// <div class="two" id="anonymous1"><!-- manually set --></div>
// <div class="two"></div>
// <div class="two"></div>

$(".two").each(function () {
    $(this).identify();
});

// Now markup is:
// <div class="two" id="anonymous1"><!-- manually set --></div>
// <div class="two" id="anonymous0"></div>
// <div class="two" id="anonymous2"></div>
Returns:

The ID of the first element or undefined if there is no first element.

Type
String | undefined

removeAria(name) → {jQuery}

Source:

Removes the named WAI-ARIA attribute from all elements in the current collection. The name is normalised (see jQuery.normaliseAria). This function is aliased as jQuery#removeAriaRef and jQuery#removeAriaState.

Example
// Markup is
// <div id="one" aria-busy="true"></div>

$("#one").removeAria("busy"); // -> jQuery(<div id="one">)

// Now markup is:
// <div id="one"></div>
Parameters:
Name Type Description
name String

WAI-ARIA attribute to remove.
Returns:

jQuery attribute representing the elements modified.

Type
jQuery

removeAriaRef(name) → {jQuery}

Source:

Alias of jQuery#removeAria.

Parameters:
Name Type Description
name String

WAI-ARIA attribute to remove.
Returns:

jQuery attribute representing the elements modified.

Type
jQuery

removeAriaState(name) → {jQuery}

Source:

Alias of jQuery#removeAria.

Parameters:
Name Type Description
name String

WAI-ARIA attribute to remove.
Returns:

jQuery attribute representing the elements modified.

Type
jQuery

removeRole(roleopt) → {jQuery}

Source:

Removes roles from the collection of elements. If the method is called without any arguments then the role attribute itself is removed. Be aware that this is not the same as passing a function which returns undefined - such an action will have no effect.

Examples

Removing a role

// Markup is:
// <div class="one" role="presentation alert"></div>
// <div class="one" role="alert"></div>

$(".one").removeRole("alert"); // -> jQuery(<div>, <div>)

// Now markup is:
// <div class="one" role="presentation"></div>
// <div class="one" role=""></div>

Completely removing a role

// Markup is:
// <div class="one" role="presentation alert"></div>
// <div class="one" role="alert"></div>

$(".one").removeRole(); // -> jQuery(<div>, <div>)

// Now markup is:
// <div class="one"></div>
// <div class="one"></div>

Removing a role with a function

// Markup is:
// <div class="one" role="presentation alert combobox"></div>

$(".one").removeRole(function (index, current) {
    return current
        .split(/\s+/)
        .filter(function (role) {
            return role.indexOf("a") > -1;
        })
        .join(" ");
    // "presentation alert"
});

// Now markup is:
// <div class="one" role="combobox"></div>
Parameters:
Name Type Attributes Description
role Attribute_Callback | String <optional>

Role(s) to remove or a function to generate the role(s) to remove.
Returns:

jQuery object representing the matched elements.

Type
jQuery

role(roleopt) → {jQuery|String|undefined}

Source:

Sets the role of all elements in the collection or gets the role of the first element in the collection, depending on whether or not the role argument is provided. As jQuery#role is just a wrapper for jQuery#attr, the role parameter can actually be any value type that the official documentation mentions.

According to the WAI-ARIA specs, an element can have mutliple roles as a space-separated list. This method will only set the role attribute to the given string when setting. If you want to modify the roles, use jQuery#addRole and jQuery#removeRole.

Examples
// Markup is:
// <div id="one"></div>
// <div id="two"></div>

$("#one").role("presentation"); // -> jQuery(<div id="one">)

// Now markup is:
// <div id="one" role="presentation"></div>
// <div id="two"></div>

$("#one").role(); // -> "presentation"
$("#two").role(); // -> undefined

Setting a role with a function

// Markup is:
// <div id="one" role="button"></div>

$("#one").role(function (index, current) {
    return current + " tooltip";
});

// Now markup is:
// <div id="one" role="button tooltip"></div>
Parameters:
Name Type Attributes Description
role Attribute_Callback | String <optional>

Role to get or function to set the role.
Returns:

Either the jQuery object representing the elements that were modified or the role value.

Type
jQuery | String | undefined