Skip to content

Add default and customizable ARIA semantics to DataGrid select column#5

Closed
Codex wants to merge 5 commits intodevfrom
codex/add-default-aria-labels
Closed

Add default and customizable ARIA semantics to DataGrid select column#5
Codex wants to merge 5 commits intodevfrom
codex/add-default-aria-labels

Conversation

@Codex
Copy link
Copy Markdown

@Codex Codex AI commented Feb 10, 2026

DataGrid row selection lacked default ARIA labels and did not expose selection state via aria-selected, blocking accessible defaults and customization.

  • Default ARIA labels: Select checkboxes now emit localized labels (“Select row {index}”, “Select all rows”) via new language resources.
  • Customizable labels: SelectColumn accepts RowCheckboxAriaLabelFunc, RowCheckboxAriaLabelledByFunc, SelectAllAriaLabel, and SelectAllAriaLabelledBy to override defaults per row/header.
  • Selection semantics: Data rows render aria-selected reflecting current selection; row index flows through CellContext to support label generation.
  • Tests: Added unit coverage for default/custom labels and aria-selected updates.

Example:

<MudDataGrid Items="people" MultiSelection>
  <Columns>
    <SelectColumn T="Person"
                  RowCheckboxAriaLabelFunc="(item, i) => $"{item.Name} row {i + 1}""
                  SelectAllAriaLabel="Select everyone" />
    <PropertyColumn T="Person" Property="p => p.Name" />
  </Columns>
</MudDataGrid>
Original prompt

This section details on the original issue you should resolve

<issue_title>Add default and customizable ARIA labeling and selection semantics to DataGrid SelectColumn</issue_title>
<issue_description>## Objective
Implement default and customizable ARIA accessibility behavior for MudDataGrid row selection checkboxes, aligned with accessibility corrections introduced in follow-up PR 125914.

This change applies only to:

  • aria-label
  • aria-labelledby
  • aria-selected

Do not implement aria-controls.


Scope & Context

  • SelectColumn.razor and SelectColumn.razor.cs control the MudCheckBox instances used for row selection in MudDataGrid.
  • The DataGrid owns selection state and must expose correct ARIA semantics by default.
  • The solution must be non-breaking and require no user configuration for standard scenarios.

Functional Requirements

1. Default ARIA labeling (no user configuration)

  • Provide default ARIA labels for selection checkboxes when no customization is supplied.
  • Must apply to:
    • Per-row selection checkboxes
    • Header “select all” checkbox

Default behavior:

  • Use aria-label by default.
  • Labels must be deterministic and screen-reader friendly.

Example expectations (illustrative):

  • Row checkbox: "Select row" or "Select row {index}"
  • Header checkbox: "Select all rows"

Do not require developers to explicitly enable this behavior.


2. Customizable ARIA labeling

  • SelectColumn must expose a way to customize ARIA labels for row selection checkboxes.
  • Customization must:
    • Be optional
    • Be context-aware (row data available)
    • Override default ARIA labels when provided

Acceptable mechanisms include (implementation choice left open):

  • Delegate (e.g., Func<TItem, string>)
  • Context-aware provider or template
  • Parameter allowing override of default ARIA attributes

If customization is supplied:

  • It must replace the default aria-label
  • It must not remove ARIA labeling entirely unless explicitly intended

3. aria-selected behavior (default and automatic)

  • Selected rows must correctly expose aria-selected="true" or "false".
  • This must reflect the actual DataGrid selection state at all times.
  • This behavior must be automatic and enabled by default.

Guidance:

  • aria-selected is applied to the row (or row-equivalent element).
  • MudCheckBox may participate in state propagation, but the DataGrid owns correctness.

No configuration should be required to enable aria-selected.


4. Explicit Non-Goals

  • Do not implement aria-controls.
  • Do not introduce breaking API changes.
  • Do not require consumers to manually wire ARIA attributes for standard DataGrid selection scenarios.

Unit Tests

Add or update unit tests to validate the following:

1. Default labeling

  • Row selection checkboxes render with a non-empty aria-label when no customization is provided.
  • Header “select all” checkbox renders with a non-empty aria-label.

2. Custom labeling

  • When a custom ARIA label provider is supplied:
    • The rendered checkbox uses the custom label.
    • The default label is not rendered.
  • Custom labels receive correct row context.

3. aria-selected state

  • Selecting a row sets aria-selected="true" on the corresponding row element.
  • Deselecting a row sets aria-selected="false".
  • Header “select all” correctly updates aria-selected on all rows.

4. Regression safety

  • Existing DataGrid selection behavior remains unchanged.
  • No exceptions or warnings occur when no ARIA customization is provided.

Tests should be written using existing MudBlazor test patterns and utilities.


Acceptance Criteria

  • Selection checkboxes are screen-reader accessible by default.
  • Developers can customize ARIA labels without re-templating the SelectColumn.
  • aria-selected accurately reflects row selection state.
  • Behavior aligns with ARIA grid / table selection best practices.
  • All new behavior is covered by unit tests.

Notes for Implementation

  • Keep logic centralized in SelectColumn / DataGrid infrastructure.
  • Prefer defaults over configuration.
  • Treat accessibility behavior as part of the public contract.
    </issue_description>

Comments on the Issue (you are @codex[agent] in this section)

@Codex Codex AI assigned Codex and versile2 Feb 10, 2026
@Codex Codex AI changed the title [WIP] Add default and customizable ARIA labeling to DataGrid SelectColumn Add default and customizable ARIA semantics to DataGrid select column Feb 10, 2026
@Codex Codex AI requested a review from versile2 February 10, 2026 19:18
@versile2 versile2 force-pushed the codex/add-default-aria-labels branch from 2f46505 to f3be919 Compare March 27, 2026 17:14
@versile2
Copy link
Copy Markdown
Owner

Superseded by MudBlazor#12911 after rebasing onto current upstream/dev and splitting the follow-up fixes into separate commits.

@versile2 versile2 closed this Mar 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add default and customizable ARIA labeling and selection semantics to DataGrid SelectColumn

2 participants