> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluid.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract.
> Authenticate with the header Authorization: Bearer <token>; public storefront read endpoints require no auth.
> Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null.
> Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy.
> The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas).
> Successful responses wrap the resource payload alongside a top-level integer status and a meta object.

# Configure cart feedback

> Configure loading spinners and optional cart toasts in a Fluid theme.

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:

```liquid theme={null}
<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:

```html theme={null}
<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:

```javascript theme={null}
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:

```javascript theme={null}
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"`:

```html theme={null}
<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:

```javascript theme={null}
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.

```css theme={null}
.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](/sdk/cart-api). For SDK installation details, see
[install FairShare](/sdk/installation).