loading-button

packages/core/src/__tests__/__e2e__/button/Button.cy.tsx

@@ -60,4 +60,16 @@ describe("Given a Button", () => {
     cy.mount(<FeatureButton />);
     cy.findByRole("button").should("have.attr", "type", "button");
   });
+  it("should have an aria-live attribute as assertive when isLoading is true", () => {
+    cy.mount(<FeatureButton isLoading />);
+    cy.findByRole("button").should("have.attr", "aria-live", "assertive");
+  });
+  it("should have overlay when isLoading is true", () => {
+    cy.mount(<FeatureButton isLoading />);
+    cy.get(".saltButton-loading-overlay").should("exist");
+  });
+  it("should have spinner when isLoading is true", () => {
+    cy.mount(<FeatureButton isLoading />);
+    cy.get(".saltButton-loading-spinner").should("exist");
+  });
 });

packages/core/src/button/Button.css

@@ -91,23 +91,23 @@
 }
 
 /* Pseudo-class applied to the root element on focus when Button is active */
-.saltButton.saltButton-active:focus-visible,
-.saltButton:focus-visible(:active) {
+.saltButton.saltButton-active:focus-visible:not(.saltButton-loading-primary, .saltButton-loading-secondary, .saltButton-loading-cta),
+.saltButton:focus-visible(:active):not(.saltButton-loading-primary, .saltButton-loading-secondary, .saltButton-loading-cta) {
   background: var(--saltButton-background-active-hover, var(--button-background));
   color: var(--saltButton-text-color-active-hover, var(--button-text-color));
   border-color: var(--saltButton-borderColor-hover, var(--button-borderColor-hover));
 }
 
 /* Pseudo-class applied to the root element on hover when Button is not active or disabled */
-.saltButton:hover {
+.saltButton:hover:not(.saltButton-loading-primary, .saltButton-loading-secondary, .saltButton-loading-cta) {
   background: var(--saltButton-background-hover, var(--button-background-hover));
   color: var(--saltButton-text-color-hover, var(--button-text-color-hover));
   border-color: var(--saltButton-borderColor-hover, var(--button-borderColor-hover));
 }
 
 /* Pseudo-class applied to the root element when Button is active and not disabled */
-.saltButton:active,
-.saltButton.saltButton-active {
+.saltButton:active:not(.saltButton-loading-primary, .saltButton-loading-secondary, .saltButton-loading-cta),
+.saltButton.saltButton-active:not(.saltButton-loading-primary, .saltButton-loading-secondary, .saltButton-loading-cta) {
   background: var(--saltButton-background-active, var(--button-background-active));
   color: var(--saltButton-text-color-active, var(--button-text-color-active));
   border-color: var(--saltButton-borderColor-active, var(--button-borderColor-active));
@@ -124,7 +124,7 @@
 /* Pseudo-class applied to the root element if disabled={true} */
 .saltButton:disabled,
 .saltButton-disabled,
-  /* Overrides to apply the disabled style when the button is focusable while also disabled */
+/* Overrides to apply the disabled style when the button is focusable while also disabled */
 .saltButton-disabled:active,
 .saltButton-disabled:focus-visible,
 .saltButton-disabled:hover {
@@ -133,3 +133,60 @@
   cursor: var(--saltButton-cursor-disabled, var(--salt-actionable-cursor-disabled));
   border-color: var(--saltButton-borderColor-disabled, var(--button-borderColor-disabled));
 }
+
+.saltButton-loading-cta,
+.saltButton-loading-cta:active,
+.saltButton-loading-cta:focus-visible,
+.saltButton-loading-cta:hover {
+  --button-borderColor: var(--salt-actionable-cta-borderColor);
+}
+
+.saltButton-loading-primary,
+.saltButton-loading-primary:active,
+.saltButton-loading-primary:focus-visible,
+.saltButton-loading-primary:hover {
+  --button-borderColor: var(--salt-actionable-primary-borderColor);
+}
+
+.saltButton-loading-secondary,
+.saltButton-loading-secondary:active,
+.saltButton-loading-secondary:focus-visible,
+.saltButton-loading-secondary:hover {
+  --button-borderColor: var(--salt-container-primary-background);
+}
+
+.saltButton-loading-overlay {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background: var(--salt-container-primary-background);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1;
+  gap: var(--salt-spacing-50);
+  border-radius: var(--saltButton-borderRadius, var(--salt-palette-corner-weak, 0));
+}
+
+.saltButton-hidden-accessible-element {
+  border: 0px solid;
+  clip: rect(0px, 0px, 0px, 0px);
+  height: 1px;
+  overflow: hidden;
+  padding: 0px;
+  position: absolute;
+  white-space: nowrap;
+  width: 1px;
+}
+
+.saltButton-hidden-element {
+  display: flex;
+  gap: var(--salt-spacing-50);
+  align-items: center;
+}
+
+.saltButton-loading-text {
+  color: var(--salt-content-primary-foreground);
+}

packages/core/src/button/Button.tsx

@@ -3,6 +3,7 @@ import { clsx } from "clsx";
 import { useComponentCssInjection } from "@salt-ds/styles";
 import { useWindow } from "@salt-ds/window";
 import { makePrefixer } from "../utils";
+import { Spinner } from "../spinner";
 
 import buttonCss from "./Button.css";
 import { useButton } from "./useButton";
@@ -26,6 +27,19 @@ export interface ButtonProps extends ComponentPropsWithoutRef<"button"> {
    * 'primary' is the default value.
    */
   variant?: ButtonVariant;
+  /**
+   * To show a loading spinner.
+   */
+  isLoading?: boolean;
+  /**
+   * For the screen reader to announce while button is in loading state
+   * 'Loading' is the default value.
+   */
+  loadingText?: string;
+  /**
+   * If `true`, a loading text with spinner will be shown while button is in loading state.
+   */
+  showLoadingText?: boolean;
 }
 
 export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
@@ -41,6 +55,9 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
       onClick,
       type = "button",
       variant = "primary",
+      isLoading,
+      loadingText = "Loading",
+      showLoadingText,
       ...restProps
     },
     ref?
@@ -72,15 +89,47 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
           withBaseName(variant),
           {
             [withBaseName("disabled")]: disabled,
+            [withBaseName(`loading-${variant}`)]: isLoading,
             [withBaseName("active")]: active,
           },
           className
         )}
+        aria-disabled={isLoading || disabled}
+        aria-live={isLoading !== undefined ? "assertive" : undefined}
         {...restProps}
         ref={ref}
         type={type}
       >
-        {children}
+        {isLoading ? (
+          <>
+            <span className={clsx(withBaseName("loading-overlay"), className)}>
+              <Spinner
+                size="small"
+                className={clsx(withBaseName("loading-spinner"), className)}
+              />
+              <span
+                className={clsx(
+                  {
+                    [withBaseName("hidden-accessible-element")]:
+                      !showLoadingText,
+                    [withBaseName("loading-text")]: showLoadingText,
+                  },
+                  className
+                )}
+              >
+                {loadingText}
+              </span>
+            </span>
+            <span
+              aria-hidden="true"
+              className={clsx(withBaseName("hidden-element"))}
+            >
+              {children}
+            </span>
+          </>
+        ) : (
+          children
+        )}
       </button>
     );
   }

packages/core/stories/button/button.stories.tsx

@@ -1,9 +1,11 @@
+import { useState } from "react";
 import { Button, ButtonProps, StackLayout } from "@salt-ds/core";
 import {
   DownloadIcon,
   SearchIcon,
   SendIcon,
   SettingsSolidIcon,
+  ChevronRightIcon,
 } from "@salt-ds/icons";
 import { Meta, StoryFn } from "@storybook/react";
 
@@ -168,3 +170,104 @@ export const FullWidth: StoryFn<typeof Button> = () => {
     </StackLayout>
   );
 };
+
+const LoadingButtonGrid = ({
+  primaryButtonLabel,
+  secondaryButtonLabel,
+  ctaButtonLabel,
+  loadingText,
+  showLoadingText,
+}: {
+  primaryButtonLabel: string;
+  secondaryButtonLabel: string;
+  ctaButtonLabel: string;
+  loadingText: string;
+  showLoadingText?: boolean;
+}) => {
+  const [primaryLoadingState, setPrimaryLoadingState] = useState(false);
+  const [secondaryLoadingState, setSecondaryLoadingState] = useState(false);
+  const [ctaLoadingState, setCtaLoadingState] = useState(false);
+
+  const handlePrimaryClick = () => {
+    setPrimaryLoadingState(true);
+    setTimeout(() => {
+      setPrimaryLoadingState(false);
+    }, 3000);
+  };
+  const handleSecondaryClick = () => {
+    setSecondaryLoadingState(true);
+    setTimeout(() => {
+      setSecondaryLoadingState(false);
+    }, 3000);
+  };
+  const handleCtaClick = () => {
+    setCtaLoadingState(true);
+    setTimeout(() => {
+      setCtaLoadingState(false);
+    }, 3000);
+  };
+
+  return (
+    <div
+      style={{
+        display: "grid",
+        gridTemplateColumns: "auto auto auto",
+        gridTemplateRows: "auto",
+        gridGap: 10,
+      }}
+    >
+      <Button
+        variant="primary"
+        showLoadingText={showLoadingText}
+        loadingText={loadingText}
+        isLoading={primaryLoadingState}
+        onClick={handlePrimaryClick}
+      >
+        {primaryButtonLabel}
+        <ChevronRightIcon aria-hidden />
+      </Button>
+      <Button
+        variant="secondary"
+        showLoadingText={showLoadingText}
+        loadingText={loadingText}
+        isLoading={secondaryLoadingState}
+        onClick={handleSecondaryClick}
+      >
+        {secondaryButtonLabel}
+        <ChevronRightIcon aria-hidden />
+      </Button>
+      <Button
+        variant="cta"
+        showLoadingText={showLoadingText}
+        loadingText={loadingText}
+        isLoading={ctaLoadingState}
+        onClick={handleCtaClick}
+      >
+        {ctaButtonLabel}
+      </Button>
+    </div>
+  );
+};
+
+export const LoadingButtons: StoryFn<typeof Button> = () => {
+  return (
+    <LoadingButtonGrid
+      primaryButtonLabel="Submit"
+      secondaryButtonLabel="Search"
+      ctaButtonLabel="Continue"
+      loadingText="Loading"
+    />
+  );
+};
+
+export const LoadingButtonsWithLabel: StoryFn<typeof Button> = () => {
+  return (
+    <LoadingButtonGrid
+      primaryButtonLabel="Next Page"
+      secondaryButtonLabel="Search"
+      ctaButtonLabel="Click to Continue"
+      loadingText="Loading"
+      showLoadingText
+    />
+  );
+};

site/docs/components/button/examples.mdx

@@ -79,5 +79,34 @@ A button with the prop `disabled={true}` will suppress all functionality. If you
 
 Use full width buttons on mobile devices or smaller viewport, the button will take up the full width of its container.
 
+</LivePreview>
+
+<LivePreview componentName="button" exampleName="LoadingButtons" >
+
+## Loading Buttons
+
+The buttons will show a loading spinner when setting the prop `isLoading` to `true`. You should pass a message using the `loadingText` prop for screenreader to announce while loading state is true. It defaults to "Loading".
+
+A Loading Button provides immediate feedback to the user after they trigger an action. It's typically used in situations where a user's action requires some processing time (more than a few seconds) before the result can be displayed. Use cases include:
+
+- Form Submission: When a user submits a [form](/salt/patterns/forms), the Loading Button indicates that the form data is being processed. This helps prevent the user from clicking the submit button multiple times, which could potentially cause duplicate submissions or errors.
+- Data Fetching: If a button triggers a data fetch from a server, a Loading Button indicates that the data is being retrieved. This is especially useful in applications where data retrieval might take a significant amount of time.
+- Processing Actions: If a button triggers a complex action that requires processing, such as generating a report or performing a calculation, a Loading Button indicates that the action is in progress.
+
+The [Content Status](salt/patterns/content-status) pattern can be displayed with a Loading Button to provide additional feedback to the user.
+
+Alternative solutions for other use cases:
+
+- Instant Actions: If an action is instantaneous or very quick. A Loading Button is not necessary.
+- Complex processing: Use a [Progress Bar](/salt/components/progress) when a task is going to take a significant amount of time (more than a few seconds) and when it's possible to estimate the progress of the task. This could be when uploading or downloading large files, installing software, or completing a multi-step process.
+
+</LivePreview>
+
+<LivePreview componentName="button" exampleName="LoadingButtonsWithLabel" >
+
+## Loading Buttons with Label
+
+The buttons will show a loading spinner when setting the prop `isLoading` to `true`. You should pass a message using the `loadingText` prop and `showLoadingText` as `true` for screenreader to announce while loading state is true. It defaults to "Loading".
+
 </LivePreview>
 </LivePreviewControls>