Accessibility

The Mini Program framework supports a subset of WAI-ARIA attributes on select base components, enabling screen readers to announce component type, name, and state to visually impaired users.

The Mini Program framework supports a subset of Accessible Rich Internet Applications (WAI-ARIA) attributes on select base components, so that screen readers can announce component type, name, and state to visually impaired users.

Limits

ARIA attributes are supported on the following eight Mini Program components: view, text, icon, button, label, checkbox, switch, and image.

Usage

Common ARIA attributes

The table below summarizes the five most commonly used ARIA attributes. Each is covered in detail in the sections that follow.

role

role is the foundation of ARIA in Mini Programs. It assigns a semantic type to a component, which the screen reader announces when the component receives focus.

Because Mini Programs use AXML syntax rather than HTML, they lack semantic tags such as <article>, <h1>, and <header>. Use the role attribute on view components to supply equivalent semantics.

Supported role values:

For a full list of WAI-ARIA roles, see WAI-ARIA.

Example: custom button

<view class="button" onTap="defaultTap" role="button" aria-label="Confirm button"
  >Confirm button</view
>

When this view receives focus, the screen reader announces Button Confirm button — the semantic type from role, followed by the name from aria-label.

Example: article structure

HTML uses semantic tags to convey document structure:

<article>
  <h1>Article Title</h1>
  <h2>Chapter 1</h2>
  <p>First paragraph...</p>
</article>

The equivalent in a Mini Program using role and aria-level:

<view role="article">
  <view role="heading" aria-level="1">Article Title</view>
  <view role="heading" aria-level="2">Chapter 1</view>
  <view>First paragraph...</view>
</view>

When a screen reader focuses on the Article Title view, it announces Article Title Heading 1. When it focuses on Chapter 1, it announces Chapter 1 Heading 2. The aria-level attribute sets the numeric heading level.

Some role values require additional attributes to function. For example, if you use role="img", you must also set the aria-label property. Otherwise, screen readers ignore the role.

aria-label

aria-label provides a text name that the screen reader announces when the component receives focus, replacing any visible text content inside the component.

Example: override visible text

<view aria-label="aria-label content">Component text content</view>

The screen reader announces aria-label content and ignores the visible text.

Example: label an image component

Use aria-label on components that have no text content, such as image:

<image src="{{src}}" role="img" aria-label="Landscape painting" />

Example: label a CSS background image

<view
  style="background-image:url(./bg.jpg);"
  role="img"
  aria-label="Landscape painting"
></view>

For highly visual components such as images, aria-label makes the announced content complete and meaningful. Without it, the screen reader can only announce the component type.

aria-labelledby

Use aria-labelledby when a component's label is a separate visible element on the page. The attribute takes the id of the label element; the screen reader reads both the component and the referenced element together.

<label>
  <checkbox aria-labelledby="content" />
  <text id="content">Checkbox content</text>
</label>

When the checkbox receives focus, the screen reader announces Not selected Checkbox content Check box.

Component id values must be unique. Avoid duplicate IDs when rendering lists.

aria-checked

aria-checked conveys whether a component is selected or not. The screen reader announces Selected or Not selected when the component receives focus.

Built-in components such as checkbox, switch, and radio handle selection state automatically. For custom implementations of these controls, set aria-checked explicitly so screen readers can read the state.

<label>
  <checkbox aria-labelledby="content" value="{{checked}}" />
  <text id="content">Checkbox content</text>
</label>

Example: custom checkbox component

<view
  class="my-checkbox"
  role="checkbox"
  onTap="handleTap"
  aria-checked="{{checked}}"
  aria-labelledby="myCheckboxText"
>
  <icon type="{{checked ? 'success' : 'clear'}}" size="12" />
  <text id="myCheckboxText">
    <slot> </slot>
  </text>
</view>

Setting role="checkbox" tells the screen reader this is a checkbox. Binding aria-checked="{{checked}}" keeps the announced state in sync with the component's data. The same pattern applies to custom switch and radio components.

aria-expanded

aria-expanded indicates whether a collapsible component — such as a dropdown menu or an accordion panel — is currently expanded or collapsed. Bind it to the component's state so the screen reader always reflects the current state.

Other ARIA attributes

For additional attributes such as aria-level, aria-disabled, and aria-hidden, see WAI-ARIA.

Related information

Accessibility enables people with disabilities, older adults, and those in constrained contexts to use products and services. Standards organizations including the W3C and the WAI publish web accessibility standards. Alipay Mini Programs implement accessibility features based on these standards.

Accessibility standards

• The Web Content Accessibility Guidelines (WCAG) define guidelines and best practices developed by accessibility experts, providing a structured framework for accessible design.

• Accessible Rich Internet Applications (WAI-ARIA) is a technical specification for making dynamic and interactive web content accessible to people with disabilities. It defines methods for browsers, media players, assistive technologies, and web content authors to achieve cross-platform accessibility.

• Mini Programs support a subset of WAI-ARIA attributes. Combine these attributes with WCAG best practices to build more accessible Mini Programs.

Enable visual accessibility features

iOS and Android both include a screen reader for users who are blind or have low vision. The screen reader announces whatever the user touches, selects, or activates.

• iOS: Go to Settings > General > Accessibility > VoiceOver and enable VoiceOver.

• Android: The screen reader is called TalkBack. The path to enable it varies by manufacturer. Refer to your device's user manual for instructions.

When a screen reader is active, it announces the content of a Mini Program component each time that component receives focus.