Skip to content

Commit 9122335

Browse files
julliermejullierme
authored
feat(material/checkbox): add new aria properties to MatCheckbox (#29457)
* feat(material/checkbox): add new aria properties to MatCheckbox Added three new aria properties to MatCheckbox: `aria-expanded`: Indicates whether the checkbox controls the visibility of another element. This should be a boolean value (true or false). `aria-controls`: Specifies the ID of the element that the checkbox controls. `aria-owns`: Specifies the ID of the element that the checkbox visually owns. These attributes will be added to the generated checkbox element if they are specified and won't be present in the HTML if not provided. Also added a small paragraph at the end of the checkbox.md file. Fixes #28761 * feat(material/checkbox): add new aria properties to MatCheckbox Added three new aria properties to MatCheckbox: `aria-expanded`: Indicates whether the checkbox controls the visibility of another element. This should be a boolean value (true or false). `aria-controls`: Specifies the ID of the element that the checkbox controls. `aria-owns`: Specifies the ID of the element that the checkbox visually owns. These attributes will be added to the generated checkbox element if they are specified and won't be present in the HTML if not provided. Also added a small paragraph at the end of the checkbox.md file. Fixes #28761 * feat(material/checkbox): add new aria properties to MatCheckbox Added three new aria properties to MatCheckbox: `aria-expanded`: Indicates whether the checkbox controls the visibility of another element. This should be a boolean value (true or false). `aria-controls`: Specifies the ID of the element that the checkbox controls. `aria-owns`: Specifies the ID of the element that the checkbox visually owns. These attributes will be added to the generated checkbox element if they are specified and won't be present in the HTML if not provided. Also added a small paragraph at the end of the checkbox.md file. Fixes #28761
1 parent 3a62ab1 commit 9122335

File tree

5 files changed

+148
-1
lines changed

5 files changed

+148
-1
lines changed

‎src/material/checkbox/checkbox.html‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,10 @@
1010
[attr.aria-labelledby]="ariaLabelledby"
1111
[attr.aria-describedby]="ariaDescribedby"
1212
[attr.aria-checked]="indeterminate ? 'mixed' : null"
13+
[attr.aria-controls]="ariaControls"
1314
[attr.aria-disabled]="disabled && disabledInteractive ? true : null"
15+
[attr.aria-expanded]="ariaExpanded"
16+
[attr.aria-owns]="ariaOwns"
1417
[attr.name]="name"
1518
[attr.value]="value"
1619
[checked]="checked"

‎src/material/checkbox/checkbox.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,3 +74,9 @@ binding these properties, as demonstrated below.
7474
<mat-checkbox [aria-label]="isSubscribedToEmailsMessage">
7575
</mat-checkbox>
7676
```
77+
78+
Additionally, `MatCheckbox` now supports the following accessibility properties:
79+
80+
- **`aria-expanded`**: Indicates whether the checkbox controls the visibility of another element. This should be a boolean value (`true` or `false`).
81+
- **`aria-controls`**: Specifies the ID of the element that the checkbox controls.
82+
- **`aria-owns`**: Specifies the ID of the element that the checkbox visually owns.

‎src/material/checkbox/checkbox.spec.ts‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -807,6 +807,94 @@ describe('MatCheckbox', () => {
807807
});
808808
});
809809

810+
describe('with provided aria-expanded', () => {
811+
let checkboxDebugElement: DebugElement;
812+
let checkboxNativeElement: HTMLElement;
813+
let inputElement: HTMLInputElement;
814+
815+
it('should use the provided postive aria-expanded', () => {
816+
fixture = createComponent(CheckboxWithPositiveAriaExpanded);
817+
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
818+
checkboxNativeElement = checkboxDebugElement.nativeElement;
819+
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
820+
821+
fixture.detectChanges();
822+
expect(inputElement.getAttribute('aria-expanded')).toBe('true');
823+
});
824+
825+
it('should use the provided negative aria-expanded', () => {
826+
fixture = createComponent(CheckboxWithNegativeAriaExpanded);
827+
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
828+
checkboxNativeElement = checkboxDebugElement.nativeElement;
829+
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
830+
831+
fixture.detectChanges();
832+
expect(inputElement.getAttribute('aria-expanded')).toBe('false');
833+
});
834+
835+
it('should not assign aria-expanded if none is provided', () => {
836+
fixture = createComponent(SingleCheckbox);
837+
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
838+
checkboxNativeElement = checkboxDebugElement.nativeElement;
839+
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
840+
841+
fixture.detectChanges();
842+
expect(inputElement.getAttribute('aria-expanded')).toBe(null);
843+
});
844+
});
845+
846+
describe('with provided aria-controls', () => {
847+
let checkboxDebugElement: DebugElement;
848+
let checkboxNativeElement: HTMLElement;
849+
let inputElement: HTMLInputElement;
850+
851+
it('should use the provided aria-controls', () => {
852+
fixture = createComponent(CheckboxWithAriaControls);
853+
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
854+
checkboxNativeElement = checkboxDebugElement.nativeElement;
855+
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
856+
857+
fixture.detectChanges();
858+
expect(inputElement.getAttribute('aria-controls')).toBe('some-id');
859+
});
860+
861+
it('should not assign aria-controls if none is provided', () => {
862+
fixture = createComponent(SingleCheckbox);
863+
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
864+
checkboxNativeElement = checkboxDebugElement.nativeElement;
865+
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
866+
867+
fixture.detectChanges();
868+
expect(inputElement.getAttribute('aria-controls')).toBe(null);
869+
});
870+
});
871+
872+
describe('with provided aria-owns', () => {
873+
let checkboxDebugElement: DebugElement;
874+
let checkboxNativeElement: HTMLElement;
875+
let inputElement: HTMLInputElement;
876+
877+
it('should use the provided aria-owns', () => {
878+
fixture = createComponent(CheckboxWithAriaOwns);
879+
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
880+
checkboxNativeElement = checkboxDebugElement.nativeElement;
881+
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
882+
883+
fixture.detectChanges();
884+
expect(inputElement.getAttribute('aria-owns')).toBe('some-id');
885+
});
886+
887+
it('should not assign aria-owns if none is provided', () => {
888+
fixture = createComponent(SingleCheckbox);
889+
checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
890+
checkboxNativeElement = checkboxDebugElement.nativeElement;
891+
inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
892+
893+
fixture.detectChanges();
894+
expect(inputElement.getAttribute('aria-owns')).toBe(null);
895+
});
896+
});
897+
810898
describe('with provided tabIndex', () => {
811899
let checkboxDebugElement: DebugElement;
812900
let checkboxNativeElement: HTMLElement;
@@ -1237,6 +1325,38 @@ class CheckboxWithAriaLabelledby {}
12371325
})
12381326
class CheckboxWithAriaDescribedby {}
12391327

1328+
/** Simple test component with an aria-expanded set with true. */
1329+
@Component({
1330+
template: `<mat-checkbox aria-expanded="true"></mat-checkbox>`,
1331+
standalone: true,
1332+
imports: [MatCheckbox],
1333+
})
1334+
class CheckboxWithPositiveAriaExpanded {}
1335+
1336+
/** Simple test component with an aria-expanded set with false. */
1337+
@Component({
1338+
template: `<mat-checkbox aria-expanded="false"></mat-checkbox>`,
1339+
standalone: true,
1340+
imports: [MatCheckbox],
1341+
})
1342+
class CheckboxWithNegativeAriaExpanded {}
1343+
1344+
/** Simple test component with an aria-controls set. */
1345+
@Component({
1346+
template: `<mat-checkbox aria-controls="some-id"></mat-checkbox>`,
1347+
standalone: true,
1348+
imports: [MatCheckbox],
1349+
})
1350+
class CheckboxWithAriaControls {}
1351+
1352+
/** Simple test component with an aria-owns set. */
1353+
@Component({
1354+
template: `<mat-checkbox aria-owns="some-id"></mat-checkbox>`,
1355+
standalone: true,
1356+
imports: [MatCheckbox],
1357+
})
1358+
class CheckboxWithAriaOwns {}
1359+
12401360
/** Simple test component with name attribute */
12411361
@Component({
12421362
template: `<mat-checkbox name="test-name"></mat-checkbox>`,

‎src/material/checkbox/checkbox.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,19 @@ export class MatCheckbox
160160
/** The 'aria-describedby' attribute is read after the element's label and field type. */
161161
@Input('aria-describedby') ariaDescribedby: string;
162162

163+
/**
164+
* Users can specify the `aria-expanded` attribute which will be forwarded to the input element
165+
*/
166+
@Input({alias: 'aria-expanded', transform: booleanAttribute}) ariaExpanded: boolean;
167+
168+
/**
169+
* Users can specify the `aria-controls` attribute which will be forwarded to the input element
170+
*/
171+
@Input('aria-controls') ariaControls: string;
172+
173+
/** Users can specify the `aria-owns` attribute which will be forwarded to the input element */
174+
@Input('aria-owns') ariaOwns: string;
175+
163176
private _uniqueId: string;
164177

165178
/** A unique id for the checkbox input. If none is supplied, it will be auto-generated. */

‎tools/public_api_guard/material/checkbox.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,9 +48,12 @@ export class MatCheckbox implements AfterViewInit, OnChanges, ControlValueAccess
4848
};
4949
// (undocumented)
5050
_animationMode?: string | undefined;
51+
ariaControls: string;
5152
ariaDescribedby: string;
53+
ariaExpanded: boolean;
5254
ariaLabel: string;
5355
ariaLabelledby: string | null;
56+
ariaOwns: string;
5457
readonly change: EventEmitter<MatCheckboxChange>;
5558
get checked(): boolean;
5659
set checked(value: boolean);
@@ -78,6 +81,8 @@ export class MatCheckbox implements AfterViewInit, OnChanges, ControlValueAccess
7881
labelPosition: 'before' | 'after';
7982
name: string | null;
8083
// (undocumented)
84+
static ngAcceptInputType_ariaExpanded: unknown;
85+
// (undocumented)
8186
static ngAcceptInputType_checked: unknown;
8287
// (undocumented)
8388
static ngAcceptInputType_disabled: unknown;
@@ -123,7 +128,7 @@ export class MatCheckbox implements AfterViewInit, OnChanges, ControlValueAccess
123128
// (undocumented)
124129
writeValue(value: any): void;
125130
// (undocumented)
126-
static ɵcmp: i0.ɵɵComponentDeclaration<MatCheckbox, "mat-checkbox", ["matCheckbox"], { "ariaLabel": { "alias": "aria-label"; "required": false; }; "ariaLabelledby": { "alias": "aria-labelledby"; "required": false; }; "ariaDescribedby": { "alias": "aria-describedby"; "required": false; }; "id": { "alias": "id"; "required": false; }; "required": { "alias": "required"; "required": false; }; "labelPosition": { "alias": "labelPosition"; "required": false; }; "name": { "alias": "name"; "required": false; }; "value": { "alias": "value"; "required": false; }; "disableRipple": { "alias": "disableRipple"; "required": false; }; "tabIndex": { "alias": "tabIndex"; "required": false; }; "color": { "alias": "color"; "required": false; }; "disabledInteractive": { "alias": "disabledInteractive"; "required": false; }; "checked": { "alias": "checked"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "indeterminate": { "alias": "indeterminate"; "required": false; }; }, { "change": "change"; "indeterminateChange": "indeterminateChange"; }, never, ["*"], true, never>;
131+
static ɵcmp: i0.ɵɵComponentDeclaration<MatCheckbox, "mat-checkbox", ["matCheckbox"], { "ariaLabel": { "alias": "aria-label"; "required": false; }; "ariaLabelledby": { "alias": "aria-labelledby"; "required": false; }; "ariaDescribedby": { "alias": "aria-describedby"; "required": false; }; "ariaExpanded": { "alias": "aria-expanded"; "required": false; }; "ariaControls": { "alias": "aria-controls"; "required": false; }; "ariaOwns": { "alias": "aria-owns"; "required": false; }; "id": { "alias": "id"; "required": false; }; "required": { "alias": "required"; "required": false; }; "labelPosition": { "alias": "labelPosition"; "required": false; }; "name": { "alias": "name"; "required": false; }; "value": { "alias": "value"; "required": false; }; "disableRipple": { "alias": "disableRipple"; "required": false; }; "tabIndex": { "alias": "tabIndex"; "required": false; }; "color": { "alias": "color"; "required": false; }; "disabledInteractive": { "alias": "disabledInteractive"; "required": false; }; "checked": { "alias": "checked"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "indeterminate": { "alias": "indeterminate"; "required": false; }; }, { "change": "change"; "indeterminateChange": "indeterminateChange"; }, never, ["*"], true, never>;
127132
// (undocumented)
128133
static ɵfac: i0.ɵɵFactoryDeclaration<MatCheckbox, [null, null, null, { attribute: "tabindex"; }, { optional: true; }, { optional: true; }]>;
129134
}

0 commit comments

Comments
 (0)