Skip to content

[Feature] Implement AutomationProperties.HelpText for accessibilityΒ #22444

@mtmattei

Description

@mtmattei

What would you like to be added? πŸ’‘

Feature Request

Summary

Implement AutomationProperties.HelpText attached property to provide supplementary accessible descriptions for screen reader users.

Current Behavior

Using AutomationProperties.HelpText produces a build warning and has no effect:

warning Uno0001: Microsoft.UI.Xaml.Automation.AutomationProperties.SetHelpText(
    Microsoft.UI.Xaml.DependencyObject,
    string
) is not implemented in Uno

Expected Behavior

HelpText should provide additional descriptive text that screen readers announce after the element's Name, giving users more context about the control's purpose or expected input.

XAML Example

<TextBox PlaceholderText="Search..."
         AutomationProperties.Name="Search tasks"
         AutomationProperties.HelpText="Type to filter the task list by title" />

<Button Content="Submit"
        AutomationProperties.Name="Submit form"
        AutomationProperties.HelpText="Saves your changes and returns to the dashboard" />

Platform Mapping

Platform Native API
iOS accessibilityHint property
Android contentDescription (combined) or AccessibilityNodeInfo.setTooltipText() (API 28+)
WASM aria-describedby or aria-description
macOS/Catalyst NSAccessibility.description
Skia/Desktop Platform-specific accessibility APIs

Difference from AutomationProperties.Name

  • Name: Primary identifier announced first (e.g., "Search tasks")
  • HelpText: Supplementary hint announced after Name (e.g., "Type to filter the task list by title")

Screen readers typically announce: "[Name], [HelpText]" giving users both identification and guidance.

Why This Matters

  • Provides instructional context for form inputs
  • Helps users understand what will happen when activating a control
  • Reduces user confusion and errors
  • Standard accessibility pattern across all platforms

WinUI Reference

Additional Context

Discovered while building an Uno Platform app following WinUI accessibility best practices. Happy to contribute a PR if guidance is provided on the implementation approach.

Why is this needed? πŸ€”

Essential for providing contextual help and instructions to screen reader users. This helps reduce errors and improves user confidence when interacting with form controls and buttons.

Renderer 🎨

  • Skia
  • Native

For which platforms πŸ“±πŸ’»πŸ–₯️

All platforms 🌍

Anything else we need to know? πŸ’¬

This is related to #22443 (AutomationProperties.HeadingLevel) - both are core AutomationProperties features needed for accessible apps.

Metadata

Metadata

Assignees

No one assigned

    Labels

    difficulty/tbdCategorizes an issue for which the difficulty level needs to be defined.kind/enhancementNew feature or requesttriage/untriagedIndicates an issue requires triaging or verification

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions