Last Updated: 19 September 2024 | Change Log

Accessibility

The SDK enables and supports you in ensuring that your checkout page meets at least an AA rating against WCAG standards.

The SDK provides some default values for certain attributes, but they are also fully customizable. Set your accessibilty configuration on initialization.

Lang

You can set the lang to specify the language of an element and all of its child elements.

By default, the lang attribute is disabled. It can be enabled to use a preset default of en-US.

You may also choose to set it to a custom language, by setting the locale to be any language supported by the BCP47 syntax. To set custom lang you must also override the default enabled setting to true.

Aria-label

The purpose of the aria-label attribute is to provide a recognizable name for an object that may not have a visible label.

By default, the aria-label is set for each of the input fields as follows:

Setting enabled to false prevent the SDK from setting any aria-labels on the input fields. Alternatively one, all or any number of the defaults may be over-written by passing custom values into the accessibility config.

Title

The title attribute is used to provide advisory information for an element, and generates a tooltip when hovering a mouse over the element.

By default, the title attribute is disabled. It can be enabled to use preset defaults, or the title for each input field can be individually set. To set custom titles you must also override the default enabled setting to true.

Example Integration

Below is an example of an accessibility configuration, where custom values are provided for every possible value. It is not necessary to provide every single one. If only a selection of custom values are passed, those not provided retain their default value.

    accessibility: {
      ariaLabel: {
        enabled: "true",
        pan: "my custom aria label for pan input",
        expiry: "my custom aria label for expiry input",
        cvv: "my custom aria label for cvv input"
      },
      lang: {
        enabled: "true",
        locale: "en-GB"
      },
      title: {
        enabled: "true",
        pan: "my custom title for pan",
        expiry: "my custom title for expiry date",
        cvv: "my custom title for security code"
      }
    }

Additional recommendations

In addition to the SDK Accessibility configuration customization, we have some recommendations to help your merchant page meet an AA rating against WCAG standards.

Display a focus indicator around the SDK fields

To display a focus indicator, define the outline CSS property in the is-onfocus class for your form fields.

CSS

.card .checkout .field.is-onfocus {
  outline: 3px solid #34ebde;
}

Use color and an icon to identify invalid fields

To change the text color of an invalid field, define the color CSS property in the input.is-invalid property of your styles configuration.

JavaScript

styles: {
  "input.is-invalid": {
    "color": "red"
  }
}

To display an icon for an invalid field, listen to the wp:field:change event and specify your styling accordingly.

JavaScript

form.addEventListener("wp:field:change", function (event) {
  if (event.detail["is-valid"] === false) {
    // code to display your invalid field icon
  } else {
    // code to remove your invalid field icon
  }
});

Display a list of invalid fields with descriptive text

Listen to the wp:field:change event and keep track of which fields are invalid.

Upon submission of the form, display text to indicate which fields are invalid.

We recommend that you display each text description in a list above the form, as well as providing a suggested correction.