Skip to content

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

TypeScript

fix(core): give CommandPalette search input an accessible name (#3982)

Baraa Hamodi767933949883
diff --git a/.changeset/commandpalette-input-label.md b/.changeset/commandpalette-input-label.md
new file mode 100644
index 0000000000..d821d38d9d
--- /dev/null
+++ b/.changeset/commandpalette-input-label.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] CommandPalette: the search input (role=combobox) now has an accessible name by default, from the new label prop or the visible placeholder. Previously screen readers announced a nameless combobox.
+@bhamodi
diff --git a/packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs b/packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs
index 24b2ddeeb3..0b6b952ad4 100644
--- a/packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs
+++ b/packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs
@@ -7,7 +7,8 @@ export const docs = {
subComponentOf: 'CommandPalette',
displayName: 'Command Palette Input',
isHiddenFromOverview: true,
- description: 'Search input slot. Auto-focuses on mount. Wires to command palette context when used inside CommandPalette.',
+ description:
+ 'Search input slot. Auto-focuses on mount. Wires to command palette context when used inside CommandPalette.',
props: [
{
name: 'placeholder',
@@ -15,16 +16,24 @@ export const docs = {
description: 'Placeholder text for the input.',
default: "'Search...'",
},
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Accessible label for the combobox input, announced by screen readers. Falls back to the placeholder text when omitted.',
+ },
{
name: 'hasAutoFocus',
type: 'boolean',
- description: 'Auto-focus the input when mounted. Automatically disabled when inside an inline command palette.',
+ description:
+ 'Auto-focus the input when mounted. Automatically disabled when inside an inline command palette.',
default: 'true',
},
{
name: 'endContent',
type: 'ReactNode',
- description: 'Content rendered at the trailing end of the input, after the spinner. Use for clear buttons or keyboard shortcut hints.',
+ description:
+ 'Content rendered at the trailing end of the input, after the spinner. Use for clear buttons or keyboard shortcut hints.',
slotElements: [
{
__element: 'Icon',
@@ -44,17 +53,20 @@ export const docs = {
{
name: 'value',
type: 'string',
- description: 'Search value. When omitted inside CommandPalette, reads from context.',
+ description:
+ 'Search value. When omitted inside CommandPalette, reads from context.',
},
{
name: 'onValueChange',
type: '(value: string) => void',
- description: 'Called when search value changes. When omitted inside CommandPalette, writes to context.',
+ description:
+ 'Called when search value changes. When omitted inside CommandPalette, writes to context.',
},
{
name: 'xstyle',
type: 'StyleXStyles',
- description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ description:
+ 'StyleX styles for layout customization. Must be a stylex.create() value.',
},
],
playground: {
@@ -69,9 +81,11 @@ export const docsZh = {
name: 'CommandPaletteInput',
isHiddenFromOverview: true,
displayName: 'Command Palette Input',
- description: '搜索输入插槽。挂载时自动聚焦。在 CommandPalette 内使用时连接到上下文。',
+ description:
+ '搜索输入插槽。挂载时自动聚焦。在 CommandPalette 内使用时连接到上下文。',
propDescriptions: {
placeholder: '输入框的占位文本。',
+ label: '组合框输入的无障碍标签,供屏幕阅读器朗读。省略时回退到占位文本。',
hasAutoFocus: '挂载时自动聚焦输入框。内联命令面板中自动禁用。',
endContent: '渲染在输入框末尾的内容,位于加载指示器之后。',
value: '搜索值。在 CommandPalette 内省略时从上下文读取。',
@@ -84,13 +98,16 @@ export const docsDense = {
name: 'CommandPaletteInput',
isHiddenFromOverview: true,
displayName: 'Command Palette Input',
- description: 'search input; auto-focus on mount; wires to context inside CommandPalette',
+ description:
+ 'search input; auto-focus on mount; wires to context inside CommandPalette',
propDescriptions: {
placeholder: 'input placeholder text',
+ label: 'accessible label for the combobox; falls back to placeholder',
hasAutoFocus: 'auto-focus on mount; auto-disabled in inline mode',
endContent: 'trailing content after spinner',
value: 'search value; reads context when omitted inside palette',
- onValueChange: 'called on change; writes context when omitted inside palette',
+ onValueChange:
+ 'called on change; writes context when omitted inside palette',
xstyle: 'StyleX layout styles; must be stylex.create() value',
},
};
diff --git a/packages/core/src/CommandPalette/CommandPaletteInput.test.tsx b/packages/core/src/CommandPalette/CommandPaletteInput.test.tsx
index 05314ce9a6..e61b932c24 100644
--- a/packages/core/src/CommandPalette/CommandPaletteInput.test.tsx
+++ b/packages/core/src/CommandPalette/CommandPaletteInput.test.tsx
@@ -32,6 +32,40 @@ describe('CommandPaletteInput', () => {
expect(screen.getByRole('combobox')).toBeInTheDocument();
});
+ it('has an accessible name by default', () => {
+ render(<CommandPaletteInput />);
+ expect(screen.getByRole('combobox')).toHaveAttribute(
+ 'aria-label',
+ 'Search…',
+ );
+ });
+
+ it('uses the label prop as the accessible name', () => {
+ render(<CommandPaletteInput label="Search commands" />);
+ const input = screen.getByRole('combobox');
+ expect(input).toHaveAttribute('aria-label', 'Search commands');
+ // The label prop does not affect the visible placeholder
+ expect(input).toHaveAttribute('placeholder', 'Search…');
+ });
+
+ it('falls back to a custom placeholder for the accessible name', () => {
+ render(<CommandPaletteInput placeholder="Type a command..." />);
+ expect(screen.getByRole('combobox')).toHaveAttribute(
+ 'aria-label',
+ 'Type a command...',
+ );
+ });
+
+ it('lets a consumer-passed aria-label override the default', () => {
+ render(
+ <CommandPaletteInput label="Search commands" aria-label="Custom name" />,
+ );
+ expect(screen.getByRole('combobox')).toHaveAttribute(
+ 'aria-label',
+ 'Custom name',
+ );
+ });
+
it('calls onValueChange when typing', () => {
const handleChange = vi.fn();
render(<CommandPaletteInput onValueChange={handleChange} />);
diff --git a/packages/core/src/CommandPalette/CommandPaletteInput.tsx b/packages/core/src/CommandPalette/CommandPaletteInput.tsx
index ac097822a3..e034fad680 100644
--- a/packages/core/src/CommandPalette/CommandPaletteInput.tsx
+++ b/packages/core/src/CommandPalette/CommandPaletteInput.tsx
@@ -109,6 +109,13 @@ export interface CommandPaletteInputProps extends Omit<
*/
placeholder?: string;
+ /**
+ * Accessible label for the combobox input, announced by screen readers.
+ * Falls back to the placeholder text (`'Search…'` by default), since a
+ * placeholder alone is not a reliable accessible name.
+ */
+ label?: string;
+
/**
* Whether to auto-focus the input when mounted.
* @default true
@@ -149,6 +156,7 @@ export function CommandPaletteInput({
value: controlledValue,
onValueChange,
placeholder: placeholderFromProps,
+ label,
hasAutoFocus = true,
endContent,
onChange,
@@ -215,6 +223,9 @@ export function CommandPaletteInput({
? ctx.getItemId(ctx.highlightedIndex)
: undefined
}
+ // A placeholder alone is not a reliable accessible name; give the
+ // combobox an explicit one (consumer aria-label via rest props wins).
+ aria-label={label ?? placeholder}
placeholder={placeholder}
value={value}
data-autofocus={effectiveAutoFocus || undefined}