Configure cart feedback

FairShare gives shoppers two forms of cart feedback:

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
  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:

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
  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.

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. For cart operation events and per-call toast suppression, see the FairShare cart API guide. For SDK installation details, see install FairShare.

Get Started

Core Concepts

Guides

Migration guides

Website & Themes

FairShare SDK

Files SDK

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