Configure cart feedback

FairShare gives shoppers two forms of cart feedback. If your theme keeps its own cart sidebar or its own add button, see Build a custom cart drawer. The two forms are:

Declarative cart buttons show a loading spinner by default.
The built-in success and error toast is opt-in.

These defaults are independent. You can keep automatic loading feedback without showing a toast.

Configure loading buttons

Buttons that use data-fluid-add-to-cart or data-fluid-add-enrollment-pack show a spinner while their request is in flight. The SDK disables the button, sets aria-busy="true", and restores the button’s previous state when the request settles. Add data-fluid-loading-text to replace the label during the request:

<button
  data-fluid-add-to-cart="{{ product.selected_or_first_available_variant.id }}"
  data-fluid-loading-text="Adding…"
>
  Add to cart
</button>

To disable automatic spinners, set the kill switch on the Fluid SDK script:

<script
  type="module"
  id="fluid-cdn-script"
  src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
  data-fluid-shop="juniper-supply"
  data-fluid-button-loading="false"
></script>

If your theme cannot edit the injected script, disable the behavior at runtime:

window.FairShareSDK?.configureCartFeedback({
  buttonLoading: false,
});

Setting data-fluid-button-loading="true" is unnecessary because the spinner is already on by default. For a custom button that calls a cart method directly, wrap the promise with withButtonLoading(). This helper clears the loading state whether the operation succeeds or throws. Every Fluid storefront creates carts in the background, so the spinner now runs until the cart is filled, not only until the request returns:

buyButton.addEventListener("click", (event) => {
  window.FairShareSDK.withButtonLoading(event.currentTarget, () =>
    window.FairShareSDK.addCartItems(48291, { quantity: 1 }),
  );
});

Enable the built-in toast

The toast remains off until you explicitly enable it. If you control the SDK script, add data-fluid-toast="true":

<script
  type="module"
  id="fluid-cdn-script"
  src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
  data-fluid-shop="juniper-supply"
  data-fluid-toast="true"
></script>

Theme JavaScript can enable and configure it after the SDK is attached:

window.addEventListener("DOMContentLoaded", () => {
  window.FairShareSDK?.configureCartFeedback({
    toast: true,
    position: "bottom-right",
    class: "theme-toast",
    messages: {
      add: "Added to your bag",
      update: "Your bag was updated",
      remove: "Removed from your bag",
      error: "We couldn't update your bag. Try again.",
    },
  });
});

Runtime configuration takes precedence over script attributes. Fields you omit continue to use the script attribute or built-in default. The error message also applies when a store that creates carts in the background cannot add the shopper’s items. See cart population failures.

Runtime key	Script attribute	Default
`toast`	`data-fluid-toast`	`false`
`buttonLoading`	`data-fluid-button-loading`	`true`
`position`	`data-fluid-toast-position`	`bottom-center`
`class`	`data-fluid-toast-class`	—
`duration`	`data-fluid-toast-duration`	`4000` milliseconds
`icon`	`data-fluid-toast-icon`	`true`
`successIcon`	`data-fluid-toast-success-icon`	Built-in success icon
`errorIcon`	`data-fluid-toast-error-icon`	Built-in error icon
`closeIcon`	`data-fluid-toast-close-icon`	`✕`
`messages`	`data-fluid-toast-msg-*`	Built-in messages

Valid positions are bottom-center, bottom-left, bottom-right, top-center, top-left, and top-right.

Style the toast

The toast renders in the light DOM, so theme CSS can target it directly. It uses id="fluid-toast" plus data-variant, data-position, and data-state attributes.

.theme-toast {
  border-radius: 8px;
  font-family: inherit;
}

.theme-toast[data-variant="success"] {
  background: #176b45;
  color: #fff;
}

.theme-toast[data-variant="error"] {
  background: #a62b2b;
  color: #fff;
}

The toast uses role="status" for success and role="alert" for errors. Shoppers can dismiss it with its close button. It also dismisses automatically after the configured duration. A custom button that wants the SDK cart drawer must also open it at the click. See Build a custom cart drawer. For cart operation events and per-call toast suppression, see the FairShare cart API guide. For SDK installation details, see install FairShare.

Start here

Building blocks

Storefront features

Advanced

Member storefront

Configure cart feedback

Configure loading buttons

Enable the built-in toast

Style the toast

​Configure loading buttons

​Enable the built-in toast

​Style the toast

Configure loading buttons

Enable the built-in toast

Style the toast