Skip to content

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

TypeScript

fix(checkbox-list): add visual loading feedback for isLoading (#2903)

Cindy Zhang4847cad18bec
diff --git a/.changeset/checkbox-list-loading-visual.md b/.changeset/checkbox-list-loading-visual.md
new file mode 100644
index 0000000000..c552323de2
--- /dev/null
+++ b/.changeset/checkbox-list-loading-visual.md
@@ -0,0 +1,5 @@
+---
+'@xds/core': patch
+---
+
+`XDSCheckboxList` now gives visual feedback while loading. When `isLoading` is set (or a `changeAction` promise is pending), items are dimmed (reduced opacity) in addition to the existing `aria-busy` and blocked interaction. Previously the loading state was only conveyed to assistive tech, with no visible change. JSDoc and component docs were corrected to match the implemented behavior.
diff --git a/apps/storybook/stories/CheckboxList.stories.tsx b/apps/storybook/stories/CheckboxList.stories.tsx
index d31cf8d2a8..e50102a498 100644
--- a/apps/storybook/stories/CheckboxList.stories.tsx
+++ b/apps/storybook/stories/CheckboxList.stories.tsx
@@ -219,6 +219,24 @@ export const Disabled: Story = {
},
};
+export const Loading: Story = {
+ render: args => {
+ const [value, setValue] = useState<string[]>(['email']);
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>
+ <XDSCheckboxListItem label="Email" value="email" />
+ <XDSCheckboxListItem label="SMS" value="sms" />
+ <XDSCheckboxListItem label="Push notification" value="push" />
+ </XDSCheckboxList>
+ );
+ },
+ args: {
+ label: 'Notification preferences',
+ isLoading: true,
+ },
+};
+
export const DisabledItem: Story = {
render: args => {
const [value, setValue] = useState<string[]>([]);
diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
index bfbff62111..b869129ce1 100644
--- a/packages/core/src/CheckboxList/CheckboxList.doc.mjs
+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
@@ -50,7 +50,8 @@ export const docs = {
{
name: 'isLoading',
type: 'boolean',
- description: 'External loading state.',
+ description:
+ 'External loading state. Dims items (reduced opacity), marks them aria-busy, and blocks interaction.',
default: 'false',
},
{
diff --git a/packages/core/src/CheckboxList/XDSCheckboxList.test.tsx b/packages/core/src/CheckboxList/XDSCheckboxList.test.tsx
index 0a94b3ad29..aabba8c2bd 100644
--- a/packages/core/src/CheckboxList/XDSCheckboxList.test.tsx
+++ b/packages/core/src/CheckboxList/XDSCheckboxList.test.tsx
@@ -419,6 +419,54 @@ describe('XDSCheckboxListItem ARIA props', () => {
expect(item).not.toHaveAttribute('aria-busy');
});
+ it('marks items aria-busy when isLoading is set', () => {
+ render(
+ <XDSCheckboxList
+ label="Prefs"
+ value={['a']}
+ onChange={() => {}}
+ isLoading>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ </XDSCheckboxList>,
+ );
+ const item = screen.getByRole('listitem');
+ expect(item).toHaveAttribute('aria-busy', 'true');
+ });
+
+ it('dims items visually when isLoading is set', () => {
+ const {rerender} = render(
+ <XDSCheckboxList label="Prefs" value={['a']} onChange={() => {}}>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ </XDSCheckboxList>,
+ );
+ const idleClass = screen.getByRole('listitem').getAttribute('class');
+
+ rerender(
+ <XDSCheckboxList
+ label="Prefs"
+ value={['a']}
+ onChange={() => {}}
+ isLoading>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ </XDSCheckboxList>,
+ );
+ const busyClass = screen.getByRole('listitem').getAttribute('class');
+
+ // Loading applies an additional style class for the dimmed appearance.
+ expect(busyClass).not.toBe(idleClass);
+ });
+
+ it('does not toggle when isLoading is set', () => {
+ const onChange = vi.fn();
+ render(
+ <XDSCheckboxList label="Prefs" value={[]} onChange={onChange} isLoading>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ </XDSCheckboxList>,
+ );
+ fireEvent.click(screen.getByRole('checkbox'));
+ expect(onChange).not.toHaveBeenCalled();
+ });
+
it('forwards arbitrary aria attributes to the list item DOM element', () => {
render(
<XDSList>
diff --git a/packages/core/src/CheckboxList/XDSCheckboxList.tsx b/packages/core/src/CheckboxList/XDSCheckboxList.tsx
index 63d2bdc58c..3f31c3de61 100644
--- a/packages/core/src/CheckboxList/XDSCheckboxList.tsx
+++ b/packages/core/src/CheckboxList/XDSCheckboxList.tsx
@@ -72,11 +72,14 @@ export interface XDSCheckboxListProps extends Omit<
onChange?: (values: string[]) => void;
/**
* Async action on change. Fires after onChange.
- * While pending, items show reduced opacity and aria-busy.
+ * While the returned promise is pending, items are dimmed (reduced
+ * opacity) and marked `aria-busy`, and interaction is blocked.
*/
changeAction?: (values: string[]) => void | Promise<void>;
/**
* Whether the checkbox group is in an external loading state.
+ * While loading, items are dimmed (reduced opacity) and marked
+ * `aria-busy`, and interaction is blocked.
* @default false
*/
isLoading?: boolean;
diff --git a/packages/core/src/CheckboxList/XDSCheckboxListItem.tsx b/packages/core/src/CheckboxList/XDSCheckboxListItem.tsx
index 92e4843cf2..20f0227c61 100644
--- a/packages/core/src/CheckboxList/XDSCheckboxListItem.tsx
+++ b/packages/core/src/CheckboxList/XDSCheckboxListItem.tsx
@@ -34,6 +34,11 @@ const styles = stylex.create({
selected: {
backgroundColor: colorVars['--color-accent-muted'],
},
+ // Loading/pending state: dim like disabled content (opacity 0.5).
+ busy: {
+ opacity: 0.5,
+ cursor: 'progress',
+ },
});
// =============================================================================
@@ -190,6 +195,8 @@ export function XDSCheckboxListItem({
!effectiveDisabled &&
!effectiveReadOnly &&
styles.selected,
+ // Dim while busy; disabled items already dim themselves.
+ isBusy && !effectiveDisabled && styles.busy,
xstyle,
] as StyleXStyles
}