Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): gate Item aria-selected on roles that permit it (#3999)

Baraa Hamodi4450e2949173
diff --git a/.changeset/item-aria-selected-role.md b/.changeset/item-aria-selected-role.md
new file mode 100644
index 0000000000..bb2bcd4271
--- /dev/null
+++ b/.changeset/item-aria-selected-role.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Item: aria-selected is now emitted only when the item's role permits it (option, tab, treeitem, grid cells), removing invalid ARIA from plain list items.
+
+@bhamodi
diff --git a/packages/core/src/Item/Item.test.tsx b/packages/core/src/Item/Item.test.tsx
index 1eef8d718f..389fcb0e2c 100644
--- a/packages/core/src/Item/Item.test.tsx
+++ b/packages/core/src/Item/Item.test.tsx
@@ -31,18 +31,13 @@ describe('Item', () => {
});
it('renders marker', () => {
- render(
- <Item label="Item" marker={<span data-testid="marker">•</span>} />,
- );
+ render(<Item label="Item" marker={<span data-testid="marker">•</span>} />);
expect(screen.getByTestId('marker')).toBeInTheDocument();
});
it('renders startContent', () => {
render(
- <Item
- label="Item"
- startContent={<span data-testid="avatar">A</span>}
- />,
+ <Item label="Item" startContent={<span data-testid="avatar">A</span>} />,
);
expect(screen.getByTestId('avatar')).toBeInTheDocument();
});
@@ -255,12 +250,7 @@ describe('Item', () => {
it('does not fire onClick when disabled item is clicked', async () => {
const onClick = vi.fn();
render(
- <Item
- label="Disabled"
- onClick={onClick}
- isDisabled
- data-testid="item"
- />,
+ <Item label="Disabled" onClick={onClick} isDisabled data-testid="item" />,
);
const item = screen.getByTestId('item');
item.dispatchEvent(new MouseEvent('click', {bubbles: true}));
@@ -276,14 +266,46 @@ describe('Item', () => {
// Selected state
// ===========================================================================
- it('applies aria-selected when isSelected', () => {
+ it('conveys selection via aria-current on the default div root', () => {
+ // aria-selected is invalid ARIA on a generic div (axe: aria-allowed-attr),
+ // so selection is exposed via aria-current, which is valid on any element.
render(<Item label="Selected" isSelected data-testid="item" />);
- expect(screen.getByTestId('item')).toHaveAttribute('aria-selected', 'true');
+ const item = screen.getByTestId('item');
+ expect(item).not.toHaveAttribute('aria-selected');
+ expect(item).toHaveAttribute('aria-current', 'true');
});
- it('does not apply aria-selected when not selected', () => {
- render(<Item label="Not Selected" data-testid="item" />);
- expect(screen.getByTestId('item')).not.toHaveAttribute('aria-selected');
+ it('applies aria-selected (not aria-current) when the role permits it', () => {
+ render(
+ <Item label="Selected" isSelected role="option" data-testid="item" />,
+ );
+ const item = screen.getByTestId('item');
+ expect(item).toHaveAttribute('aria-selected', 'true');
+ // A permitted role uses aria-selected; aria-current would be redundant.
+ expect(item).not.toHaveAttribute('aria-current');
+ });
+
+ it('falls back to aria-current when the role does not permit aria-selected', () => {
+ render(
+ <Item label="Selected" isSelected role="menuitem" data-testid="item" />,
+ );
+ const item = screen.getByTestId('item');
+ expect(item).not.toHaveAttribute('aria-selected');
+ expect(item).toHaveAttribute('aria-current', 'true');
+ });
+
+ it('applies neither aria-selected nor aria-current when not selected', () => {
+ render(<Item label="Not Selected" role="option" data-testid="item" />);
+ const item = screen.getByTestId('item');
+ expect(item).not.toHaveAttribute('aria-selected');
+ expect(item).not.toHaveAttribute('aria-current');
+ });
+
+ it('lets a consumer-provided aria-current win over the selection default', () => {
+ render(
+ <Item label="Step" isSelected aria-current="step" data-testid="item" />,
+ );
+ expect(screen.getByTestId('item')).toHaveAttribute('aria-current', 'step');
});
// ===========================================================================
diff --git a/packages/core/src/Item/Item.tsx b/packages/core/src/Item/Item.tsx
index 0d7407bddf..4817c041df 100644
--- a/packages/core/src/Item/Item.tsx
+++ b/packages/core/src/Item/Item.tsx
@@ -131,7 +131,12 @@ export interface ItemProps extends BaseProps<HTMLElement> {
isHighlighted?: boolean;
/**
- * Selected state.
+ * Selected state. Always applies the selected visual styling. When `role`
+ * permits it (option, tab, row, gridcell, columnheader, rowheader, treeitem)
+ * the state is exposed as `aria-selected`; otherwise (e.g. a listitem or a
+ * bare div, where `aria-selected` is invalid ARIA) it falls back to
+ * `aria-current="true"` so assistive tech is still told which item is
+ * selected. A consumer-provided `aria-current` always wins.
* @default false
*/
isSelected?: boolean;
@@ -148,6 +153,24 @@ export interface ItemProps extends BaseProps<HTMLElement> {
'data-testid'?: string;
}
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Roles on which WAI-ARIA permits the aria-selected attribute.
+ * https://www.w3.org/TR/wai-aria-1.2/#aria-selected
+ */
+const ARIA_SELECTED_ROLES = new Set([
+ 'option',
+ 'tab',
+ 'row',
+ 'gridcell',
+ 'columnheader',
+ 'rowheader',
+ 'treeitem',
+]);
+
// =============================================================================
// Styles
// =============================================================================
@@ -346,6 +369,11 @@ export function Item({
// handles keyboard access. Skip the invisible button/anchor and put
// onClick directly on the root element instead.
const hasParentRole = role != null;
+ // aria-selected is only valid on selectable roles (option, tab, treeitem,
+ // grid cells). On the default div/li root the attribute is invalid ARIA
+ // (axe: aria-allowed-attr), so selection stays visual-only there — callers
+ // that need selection semantics pass a permitted role.
+ const allowsAriaSelected = role != null && ARIA_SELECTED_ROLES.has(role);
const isStringLabel = typeof label === 'string';
const isStringDescription = typeof description === 'string';
@@ -471,7 +499,15 @@ export function Item({
<Component
ref={ref as React.Ref<never>}
{...restProps}
- aria-selected={isSelected || undefined}
+ aria-selected={(allowsAriaSelected && isSelected) || undefined}
+ // aria-selected is invalid on roles that don't permit it (listitem, a
+ // bare div, etc.). For those, convey selection via aria-current — valid
+ // on any element — so the state still reaches AT. Written after
+ // {...restProps} so it must defer to a consumer-provided aria-current.
+ aria-current={
+ restProps['aria-current'] ??
+ (isSelected && !allowsAriaSelected ? true : undefined)
+ }
aria-disabled={isDisabled || undefined}
{...mergeProps(
themeProps('item', {density, align}),
diff --git a/packages/core/src/List/List.test.tsx b/packages/core/src/List/List.test.tsx
index 22d2ed106b..aace5c0388 100644
--- a/packages/core/src/List/List.test.tsx
+++ b/packages/core/src/List/List.test.tsx
@@ -436,11 +436,7 @@ describe('List', () => {
it('sets target on anchor when provided', () => {
const {container} = render(
<List>
- <ListItem
- label="External"
- href="https://example.com"
- target="_blank"
- />
+ <ListItem label="External" href="https://example.com" target="_blank" />
</List>,
);
const anchor = container.querySelector('a');
@@ -500,17 +496,21 @@ describe('List', () => {
// Selected state
// ===========================================================================
- it('applies aria-selected when isSelected', () => {
+ it('conveys selection via aria-current when isSelected', () => {
+ // aria-selected is not permitted on an li (role listitem, axe:
+ // aria-allowed-attr), so selection is exposed via aria-current — valid on
+ // any element — so screen-reader users are still told which item is chosen.
const {container} = render(
<List>
<ListItem label="Selected" isSelected onClick={() => {}} />
</List>,
);
const item = container.querySelector('.astryx-item');
- expect(item).toHaveAttribute('aria-selected', 'true');
+ expect(item).not.toHaveAttribute('aria-selected');
+ expect(item).toHaveAttribute('aria-current', 'true');
});
- it('does not apply aria-selected when not selected', () => {
+ it('applies neither aria-selected nor aria-current when not selected', () => {
const {container} = render(
<List>
<ListItem label="Not Selected" />
@@ -518,6 +518,7 @@ describe('List', () => {
);
const li = container.querySelector('li');
expect(li).not.toHaveAttribute('aria-selected');
+ expect(li).not.toHaveAttribute('aria-current');
});
// ===========================================================================