Skip to content

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

TypeScript

feat(InputClearButton): tooltip says "Clear"; accessible name keeps the field label (#7476)

Cindy Zhang75e430144df9
diff --git a/.changeset/input-clear-tooltip-generic.md b/.changeset/input-clear-tooltip-generic.md
new file mode 100644
index 0000000000..6f172f144d
--- /dev/null
+++ b/.changeset/input-clear-tooltip-generic.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Clearable inputs: the clear button's tooltip now reads just "Clear" (localized) instead of repeating the field's label, so a long label no longer turns into awkward tooltip copy such as "Clear Assigned engineering partner". The button's accessible name is unchanged and still names the field, such as "Clear Search". Applies to every input that renders the shared clear button, including `TextInput`, `NumberInput`, the date and time inputs, `FileInput`, `Selector`, `MultiSelector`, `Typeahead`, and `Tokenizer`. Override the new `@astryx.inputClearButton.tooltip` catalog key to change the wording.
+
+@athz @cixzhang
diff --git a/docs/families/input-fields.md b/docs/families/input-fields.md
index 9d9a7fe2de..bfab38120d 100644
--- a/docs/families/input-fields.md
+++ b/docs/families/input-fields.md
@@ -221,6 +221,12 @@ another implementation helper.
component's own handler through the shared composition helper, component-first
unless the API promises cancellation. No member and no layout may vary this.
+- **FR11 — The clear control's tooltip names the action, not the field.**
+ Every member's clear control MUST show the localized generic tooltip "Clear"
+ on hover and keyboard focus, whatever the field's label or the scope of the
+ clear. Its accessible name stays contextual and member-owned, such as "Clear
+ Search" or "Clear all Countries", and contains the visible word.
+
## Allowed component variation
- **AV1 — Native versus composed control.** Text fields may use native inputs;
@@ -392,6 +398,7 @@ The exhaustive coverage obligation follows the membership and adoption tables.
| FR8 | Representative member tests plus real-browser overlap/opacity/height checks | eligible single-line direct controls; wrapped, custom, tall, and translucent controls; all three placements | Attached is missing where supported, appears where unsafe, or tooltip reaches direct FieldStatus |
| FR9 | `inputFontFloor.test.ts`, focused computed-style checks, and real iOS Safari focus evidence | iOS touch, non-iOS coarse pointer, and desktop fine pointer | iOS renders below 16 CSS px or focus zooms, or a non-iOS coarse pointer receives the iOS-only floor |
| FR10 | A type test over every Field-composed component's props that fails if one accepts root `xstyle`, `className`, or `style`; per-component render tests for every base prop, `container*`, and `control*` prop and for both development warnings | every Field-composed component standalone, in horizontal-label FormLayout, and inside InputGroup where admitted | A component type-checks with root styling, a base prop lands off the primary semantic control, `container*` lands off the Field box or on the control box, `control*` lands off the control box, or a warning is missing |
+| FR11 | `InputClearButton.test.tsx` tooltip and accessible-name assertions, plus real-Chromium hover captures | a long field label; a locale override; light and dark | The tooltip repeats the field label, or the accessible name loses the field label |
## Decision links
@@ -502,6 +509,17 @@ rather than moving to another element.
Rejected: keeping root `xstyle` and routing it to Field; spreads and wrappers would move styling silently.
+### DEC-9 — The clear tooltip names only the action
+
+**Decider:** `cixzhang`, `2026-10-13`
+
+The field's label already sits beside the clear glyph, so a sighted person
+needs only the action. Repeating the label makes long or noun-phrase labels
+read as awkward copy. A screen-reader user does not see the field around the
+button, so the accessible name keeps the label.
+
+Rejected: a tooltip that repeats the accessible name; it doubles the label on screen.
+
## Open questions
None.
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 9e2096c626..b4b127e594 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -1407,6 +1407,10 @@
"defaultMessage": "{count, number} {count, plural, one {character} other {characters}} over the limit",
"description": "Screen-reader-only assertive announcement when the user has typed past a TextArea's maxLength. `{count}` is how many characters over — example: `3 characters over the limit`."
},
+ "@astryx.inputClearButton.tooltip": {
+ "defaultMessage": "Clear",
+ "description": "Tooltip shown on hover or keyboard focus over the X button inside an input that clears its value. Verb, imperative. Shown alone beside the field, so it names only the action; the screen-reader label names the field separately."
+ },
"@astryx.textInput.clearLabel": {
"defaultMessage": "Clear {label}",
"description": "Screen-reader-only label on the X that clears the value from a TextInput. Example: `Clear Email`, `Clear Name`."
diff --git a/packages/core/src/Field/InputClearButton.test.tsx b/packages/core/src/Field/InputClearButton.test.tsx
index 4eadda11bb..fe32801b24 100644
--- a/packages/core/src/Field/InputClearButton.test.tsx
+++ b/packages/core/src/Field/InputClearButton.test.tsx
@@ -25,6 +25,7 @@ import {
type InputClearButtonProps,
} from './InputClearButton';
import {Icon, registerIcons, resetIcons} from '../Icon';
+import {InternationalizationProvider} from '../i18n';
import {defineTheme} from '../theme/defineTheme';
import {generateThemeCSS} from '../theme/generateThemeRules';
import {declaredValue} from '../__tests__/stylexDeclarations';
@@ -95,13 +96,23 @@ describe('InputClearButton public props', () => {
});
describe('InputClearButton', () => {
- it('uses the contextual label for the tooltip and accessible name', async () => {
+ it('shows a generic "Clear" tooltip while the accessible name keeps the field label', async () => {
+ // A long field label repeated in the tooltip reads as awkward copy
+ // ("Clear Assigned engineering partner"); the field's own label already
+ // sits beside the glyph. The contextual name stays for assistive tech.
const showPopover = vi.spyOn(HTMLElement.prototype, 'showPopover');
- render(<InputClearButton label="Clear Search" onClick={() => {}} />);
+ render(
+ <InputClearButton
+ label="Clear Assigned engineering partner"
+ onClick={() => {}}
+ />,
+ );
- const button = screen.getByRole('button', {name: 'Clear Search'});
+ const button = screen.getByRole('button', {
+ name: 'Clear Assigned engineering partner',
+ });
const tooltip = screen.getByRole('tooltip', {hidden: true});
- expect(tooltip).toHaveTextContent(/^Clear Search$/);
+ expect(tooltip).toHaveTextContent(/^Clear$/);
expect(button.getAttribute('aria-describedby')).toBe(tooltip.id);
fireEvent.mouseEnter(button);
@@ -109,6 +120,20 @@ describe('InputClearButton', () => {
showPopover.mockRestore();
});
+ it('localizes the tooltip through the catalog', () => {
+ render(
+ <InternationalizationProvider
+ locale="en"
+ overrides={{en: {'@astryx.inputClearButton.tooltip': 'Leeren'}}}>
+ <InputClearButton label="Suche leeren" onClick={() => {}} />
+ </InternationalizationProvider>,
+ );
+ expect(screen.getByRole('button', {name: 'Suche leeren'})).toBeTruthy();
+ expect(screen.getByRole('tooltip', {hidden: true})).toHaveTextContent(
+ /^Leeren$/,
+ );
+ });
+
it('renders a real button with the given accessible label', () => {
render(<InputClearButton label="Clear" onClick={() => {}} />);
const button = screen.getByRole('button', {name: 'Clear'});
diff --git a/packages/core/src/Field/InputClearButton.tsx b/packages/core/src/Field/InputClearButton.tsx
index 85912bc295..a9e154f095 100644
--- a/packages/core/src/Field/InputClearButton.tsx
+++ b/packages/core/src/Field/InputClearButton.tsx
@@ -4,9 +4,10 @@
/**
* @file InputClearButton.tsx
- * @input Uses React, Button, and Icon
- * @output Exports the public InputClearButton and an internal popup-aware variant,
- * both with a contextual tooltip matching their required label.
+ * @input Uses React, Button, Icon, and the i18n translator
+ * @output Exports the public InputClearButton and an internal popup-aware variant.
+ * Both show the localized generic "Clear" tooltip and keep the caller's
+ * contextual label as the accessible name.
* @position Shared primitive. Every input that renders a clear affordance —
* TextInput, NumberInput, TimeInput, DateInput, DateTimeInput,
* DateRangeInput, Selector, MultiSelector, Typeahead, Tokenizer, FileInput —
@@ -19,6 +20,7 @@ import type {ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {Button} from '../Button';
import {Icon} from '../Icon';
+import {useTranslator} from '../i18n';
import {themeProps} from '../utils/themeProps';
const styles = stylex.create({
@@ -67,7 +69,10 @@ const styles = stylex.create({
});
export interface InputClearButtonProps {
- /** Contextual accessible name for the button, such as "Clear Search". */
+ /**
+ * Contextual accessible name for the button, such as "Clear Search". The
+ * visible tooltip is always the localized generic "Clear".
+ */
label: string;
onClick: (e: React.MouseEvent<HTMLButtonElement>) => void;
xstyle?: stylex.StyleXStyles;
@@ -83,10 +88,11 @@ interface InternalInputClearButtonProps extends InputClearButtonProps {
type InputClearButtonRenderProps = InputClearButtonProps &
Partial<
Pick<InternalInputClearButtonProps, 'onPointerDown' | 'onClickCapture'>
- >;
+ > & {tooltip: string};
function renderInputClearButton({
label,
+ tooltip,
onClick,
onPointerDown,
onClickCapture,
@@ -100,7 +106,11 @@ function renderInputClearButton({
variant="ghost"
size="sm"
label={label}
- tooltip={label}
+ // The field's label already sits beside the glyph, so the tooltip names
+ // only the action; repeating a long label reads as awkward copy. The
+ // contextual label stays the accessible name, which still contains
+ // the visible word (WCAG 2.5.3, label in name).
+ tooltip={tooltip}
className={buttonTargetClassName}
icon={
<Icon
@@ -128,14 +138,22 @@ function renderInputClearButton({
}
export function InputClearButton(props: InputClearButtonProps): ReactNode {
- return renderInputClearButton(props);
+ const t = useTranslator();
+ return renderInputClearButton({
+ ...props,
+ tooltip: t('@astryx.inputClearButton.tooltip'),
+ });
}
/** Internal variant used while popup-aware clear behavior is rolled out. */
export function InternalInputClearButton(
props: InternalInputClearButtonProps,
): ReactNode {
- return renderInputClearButton(props);
+ const t = useTranslator();
+ return renderInputClearButton({
+ ...props,
+ tooltip: t('@astryx.inputClearButton.tooltip'),
+ });
}
InputClearButton.displayName = 'InputClearButton';