Last updated

Fluid Web Widgets

This package provides web components for integrating Fluid into your website. It supports two distribution methods:

  1. NPM Package - For bundled applications
  2. CDN / Script Tag - For direct inclusion in HTML

Distribution Methods

NPM Package Distribution

Use this method if you're building a modern JavaScript application with a bundler (webpack, Vite, etc.).

Installation

# Using npm
npm install @fluid-app/web-widgets

# Using yarn
yarn add @fluid-app/web-widgets

# Using pnpm
pnpm add @fluid-app/web-widgets

Usage

// Import the components and styles
import { initializeFluid } from "@fluid-app/fluid";
import { registerWebComponents } from "@fluid-app/web-widgets";

import "@fluid-app/web-widgets/styles.css";

// Initialize Fluid SDK with your shop ID
initializeFluid({
  fluidShop: "your-shop-id",
  attributionSettings: {
    pathAttributionPattern: "/influencer/([^/]+)",
  },
});

// Register the web components
registerWebComponents();

Then use the components in your HTML:

<fluid-cart-widget
  position="bottom-right"
  fluid-shop-display-name="Your Store Name"
></fluid-cart-widget>

CDN / Script Tag Distribution

Use this method for direct inclusion in a website without a build step.

<script
  id="fluid-cdn-script"
  src="https://assets.fluid.app/scripts/web-widgets/index.js"
  data-fluid-shop="your-shop-id"
  data-path-attribution-pattern="([^/]+)/shop"
></script>

<!-- Add the cart widget anywhere on your page -->
<fluid-cart-widget
  position="bottom-right"
  fluid-shop-display-name="Your Store Name"
></fluid-cart-widget>

Key Benefits of CDN Distribution

  • No NPM installation required - Works with any HTML page
  • Automatic style injection - No separate CSS file to include
  • Single script tag does everything - Initializes SDK, loads styles, registers components

Controlling the Cart

There are two ways to control the cart functionality:

Declarative Controls (HTML)

Use data attributes for the simplest implementation:

<button data-fluid-cart="open">Open Cart</button>
<button data-fluid-cart="close">Close Cart</button>
<button data-fluid-cart="toggle">Toggle Cart</button>

JavaScript Controls

For programmatic control:

// When using NPM package
import { closeCart, openCart, toggleCart } from "@fluid-app/react-widgets";

openCart();
closeCart();
toggleCart();

// When using CDN
window.fluidCart.open();
window.fluidCart.close();
window.fluidCart.toggle();

Displaying Cart Count

You can easily display the current cart item count anywhere on your page by using an element with the ID fluid-cart-count. The SDK will automatically update this element whenever the cart changes.

<!-- Simple cart count display -->
<span id="fluid-cart-count">0</span>

<!-- Cart count with styling -->
<div class="cart-icon">
  <i class="fas fa-shopping-cart"></i>
  <span class="badge" id="fluid-cart-count">0</span>
</div>

The cart count is updated automatically when:

  • Items are added to the cart
  • Items are removed from the cart
  • Item quantities are updated
  • The cart is cleared
  • A new cart is created
  • The cart is refreshed from the API

Adding Products to Cart

Declarative Product Controls (HTML)

Use data attributes to add products to cart without writing JavaScript:

<!-- Add a single product (variant) to cart -->
<button data-fluid-add-to-cart="123456">Add to Cart</button>

<!-- Specify quantity -->
<button data-fluid-add-to-cart="123456" data-fluid-quantity="2">
  Add 2 to Cart
</button>

<!-- Add to cart and open cart drawer immediately -->
<button data-fluid-add-to-cart="123456" data-fluid-open-cart-after-add="true">
  Add to Cart and View
</button>

<!-- Add with subscription enabled -->
<button data-fluid-add-to-cart="123456" data-fluid-subscribe="true">
  Add with Subscription
</button>

<!-- Add multiple products with different subscription settings -->
<button
  data-fluid-add-to-cart="123456,789012"
  data-fluid-subscribe="true,false"
>
  Add Multiple Items
</button>

<!-- Combine subscription with quantity and cart opening -->
<button
  data-fluid-add-to-cart="123456"
  data-fluid-subscribe="true"
  data-fluid-quantity="2"
  data-fluid-open-cart-after-add="true"
>
  Add 2 with Subscription and View
</button>

Adding Enrollment Packs

Enrollment packs can be added to the cart using data attributes:

<!-- Add an enrollment pack to cart -->
<button data-fluid-add-enrollment-pack="42">Add Enrollment Pack</button>

<!-- Add enrollment pack and open cart drawer immediately -->
<button
  data-fluid-add-enrollment-pack="42"
  data-fluid-open-cart-after-add="true"
>
  Add Enrollment Pack and View
</button>

Customizing Widget Styles

You can customize the widgets to match your brand's color scheme using CSS variables:

/* In your CSS file */
:root {
  --company-color: #3461ff; /* Replace with your brand color */
}

Available Components

Cart Widget (<fluid-cart-widget>)

Attribute/PropertyTypeDefaultDescription
positionstring'bottom-right'Position on screen: 'top-left', 'top-right', 'bottom-left', 'bottom-right'
sizenumber60Size of the widget button in pixels
x-marginnumber40Horizontal margin from the edge of the screen in pixels
y-marginnumber98Vertical margin from the edge of the screen in pixels
z-indexnumber50Z-index for layering
fluid-shop-display-namestring'My Store'Shop name displayed in the cart header
hide-widgetbooleanfalseWhen true, hides button but keeps cart functionality

For More Information

For full documentation on attribution settings and advanced configuration, refer to the @fluid-app/fluid documentation.

For a complete working example, see the cdn-example.html file in this package.