Checkbox Aria TagHelper for ASP.NET Core Accessibility

Checkbox Aria TagHelper

Karen Payne’s Checkbox Aria TagHelper automates aria-checked attribute management for ASP.NET Core checkboxes. It ensures screen readers accurately reflect checkbox states during page load and user interactions.

Why This Matters

Screen readers rely on aria-checked to convey checkbox states to users with visual impairments. Manual synchronization is error-prone and time-consuming, leading to inconsistent accessibility. Failure to implement this can exclude 2.2 billion people with disabilities from fully using web applications, per WHO data.

Key Insights

• “TagHelper sets aria-checked based on checked attribute on page load”: Karen Payne’s implementation (2025)
• “JavaScript updates aria-checked on checkbox change events”: Ensures real-time accessibility for dynamic UIs
• “Used in ASP.NET Core projects requiring screen reader compatibility”: Demonstrated in DEV Community example

Working Example

using Microsoft.AspNetCore.Razor.TagHelpers;
[HtmlTargetElement("input", Attributes = "asp-for")]
public class CheckboxAriaTagHelper : TagHelper
{
    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        if (!output.Attributes.TryGetAttribute("type", out var type) || type.Value.ToString() != "checkbox") return;
        var isChecked = output.Attributes.TryGetAttribute("checked", out var chk);
        output.Attributes.SetAttribute("aria-checked", isChecked);
    }
}

@section Scripts {
<script>
document.addEventListener("DOMContentLoaded", () => {
    document.querySelectorAll("input.js-aria-checkbox[type='checkbox']").forEach(function (cb) {
        cb.addEventListener("change", function () {
            this.setAttribute("aria-checked", this.checked ? "true" : "false");
        });
    });
});
</script>
}

Practical Applications

• Use Case: ASP.NET Core apps requiring screen reader compatibility for checkboxes
• Pitfall: Forgetting to add js-aria-checkbox class causes JavaScript event handlers to fail

References:

• https://dev.to/karenpayneoregon/checkbox-aria-taghelper-g6b

---