**Last updated**: 24 June 2025 | [**Change log**](/products/checkout/web/changelog/)

# 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 accessibility 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:

| Parameter | Default |
|  --- | --- |
| `enabled` | true |
| `pan` | "Card number" |
| `expiry` | "Expiry date" |
| `cvv` | "Security code" |
| `cvvOnly` | "Security code" |


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 `title`s you must also override the default `enabled` setting to `true`.

| Parameter | Default |
|  --- | --- |
| `enabled` | false |
| `pan` | "Card number" |
| `expiry` | "Expiry date" |
| `cvv` | "Security code is the 3 or 4 digit number that is unique to each card and only appears on the card itself" |
| `cvvOnly` | "Security code is the 3 or 4 digit number that is unique to each card and only appears on the card itself" |


Note
Relying on the title attribute alone is discouraged; many user agents do not expose the attribute in an accessible manner. Often they require a mouse to cause a tooltip to appear. This is not accessible to keyboard-only and touch-only users.

#### 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.


```css
    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.

Note
Make sure you are familiar with the [Styles](/products/checkout/web/styles) and [Event hooks](/products/checkout/web/event-hooks) supported by the SDK.

#### 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


```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


```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


```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.

Note
Visit [w3.org](https://www.w3.org/WAI/standards-guidelines/wcag/) for more information on accessibility.