FairShare Web Components

FairShare ships four web components that you place directly in your HTML markup: <fluid-cart-widget>, <fluid-banner-widget>, <fluid-lead-capture-widget>, and <fluid-media-widget>. The SDK registers a component when its tag appears on the page, so you do not need an import or build step.

When to Use

Use <fluid-cart-widget> to add a floating cart button and slide-out cart sidebar to your site. The widget displays a live item count, lets shoppers review and edit their cart, and links to checkout. If you want to build a fully custom cart UI, you can hide the widget with hideWidget and drive the cart panel with the JavaScript cart controls instead.

Usage

<fluid-cart-widget
  position="bottom_right"
  fluidShopDisplayName="Your Store Name"
></fluid-cart-widget>

Attributes

Attribute	Type	Default	Description
`useBrand`	boolean	`false`	Apply brand colors from your Fluid shop settings
`primaryColor`	string	—	Primary color as a hex value, e.g. `#3461ff`
`position`	string	`bottom_right`	Screen corner for the floating button: `bottom_right`, `bottom_left`, `top_right`, `top_left`
`size`	number	`60`	Diameter of the floating cart button in pixels
`hideWidget`	boolean	`false`	Hide the floating button while keeping the cart panel functional
`alwaysOpen`	boolean	`false`	Keep the cart sidebar permanently open (useful for dedicated cart pages)
`fluidShopDisplayName`	string	—	Display name for the shop shown inside the cart widget

JavaScript Settings Override

Override widget settings at runtime using cart.settings.set(). Settings are scoped to the current URL path, so you can apply different configurations on different pages without changing the HTML.

window.FairShareSDK.cart.settings.set({
  hideWidget: false,
  position: "bottom_right",
  size: 60,
  placement: "right",
  primaryColor: "#3461ff",
  secondaryColor: "#2d3748",
  xMargin: 16,
  yMargin: 16,
});

// Read active settings
const settings = window.FairShareSDK.cart.settings.get();

// Reset to component-level defaults
window.FairShareSDK.cart.settings.clear();

When to Use

Use <fluid-lead-capture-widget> when you want a ready-made contact form that submits leads directly to Fluid. The widget handles field rendering, validation, submission, and success messaging. It’s ideal for landing pages, contact sections, or anywhere you want to collect prospects without writing form-handling code.

Usage

<fluid-lead-capture-widget
  title="Get in touch"
  description="We'd love to hear from you"
  submit-button-text="Send"
  success-message="Thanks! We'll be in touch."
  contact-method="email"
  position="bottom_right"
></fluid-lead-capture-widget>

Common attributes include:

Attribute	Description
`title`	Heading displayed at the top of the form
`description`	Subheading or instructional text below the title
`submit-button-text`	Label for the form’s submit button
`success-message`	Message shown after a successful submission
`contact-method`	Contact field to show: `email` or `phone`. Defaults to `email`
`position`	Screen position of the widget trigger button: `bottom_right`, `bottom_left`, `top_right`, `top_left`
`size`	Size of the widget trigger button in pixels
`hide-widget`	Hide the trigger button while keeping the form accessible programmatically

Programmatic Lead Capture

If you’re building a custom form or capturing leads as part of another flow, submit directly via JavaScript without rendering the widget:

await window.FairShareSDK.captureLead({
  message: "I'm interested in the starter kit",
  contact: {
    name: "Dana Whitfield",
    email: "dana.whitfield@example.com",
  },
});

Pass the prospect’s details inside contact — name, email, and phone. Keys outside that shape are dropped silently, so a flat payload submits an empty lead and still resolves successfully. Every field is optional, but send at least one of email or phone so the lead is reachable. The captured lead is attributed to the same rep that was resolved when the SDK initialized.

Affiliate hydration

FairShare can fill affiliate-specific names, images, links, and visibility states into a shared storefront page after it loads. Use the affiliate hydration guide to choose between custom elements, data attributes, and URL sentinels without duplicating a page for every affiliate.

When to Use

Use <fluid-media-widget> to embed a product video, media file, or an entire playlist without building a custom player. The widget supports both inline and popover display modes, making it suitable for product pages, landing pages, and lightbox-style media galleries.

Usage

<fluid-media-widget
  playlist-id="spring-launch-demos"
  embed-type="popover"
  auto-open="false"
></fluid-media-widget>

Attributes

These are the attributes you’ll reach for most often. The widget accepts more than these — sizing, video-playback options, and event-callback hooks among them — so treat this table as a starting point rather than the complete set.

Attribute	Type	Default	Description
`playlist-id`	string	—	Slug or ID of the playlist to display
`media-id`	string	—	Slug or ID of a single media item to display
`embed-type`	string	`default`	Display mode: `default`, `popover`, `inline`, or `inline-shopping`
`auto-open`	boolean	`false`	Automatically open the media on page load

Use playlist-id to show a browsable collection. Use media-id to show one item. If you provide both, playlist-id takes precedence. The widget does not recognize library-id. For playback events and CTA overrides, see the FairShare media guide.

JavaScript methods

Fetch media metadata to build custom players or display additional information alongside the widget:

// Fetch a media library by slug or ID
const libraryResponse =
  await window.FairShareSDK.getLibrary("spring-launch-demos");
const library = libraryResponse.library;

// Fetch a single media item by slug or ID
const mediaResponse =
  await window.FairShareSDK.getMedia("unboxing-the-starter-kit");
const media = mediaResponse.media;

The methods return response wrappers. Read playlist content from libraryResponse.library, including title and library_items. Read the media record from mediaResponse.media.

CSS Customization

FairShare components expose CSS custom properties (variables) that you can set in your stylesheet to match your brand. Define them on :root to apply them globally:

:root {
  --company-color: #3461ff;
  --ff-body: "Your Custom Font", sans-serif;
}

Variable	Description
`--company-color`	Primary brand color used in buttons, links, and accents across all widgets
`--ff-body`	Body font stack applied to widget text

For colors, provide a valid CSS hex, RGB, or HSL value. For fonts, list your custom font first and include a generic family fallback.

Analytics and Events

Track events and inspect attribution state from anywhere in your JavaScript code. Firing a tracked event:

window.FairShareSDK.trackFairshareEvent({
  eventName: "CHECKOUT_STARTED",
  data: { cart_token: "7Hq2Kd9Rm4bV1nX" },
});

eventName accepts exactly one value, "CHECKOUT_STARTED". Any other name is accepted at the call site but never reaches Fluid, and nothing raises an error — so the call looks successful while no event is recorded. The method returns nothing — call it directly rather than awaiting it. Tracking checkout started:

window.FairShareSDK.trackCheckoutStarted({ cart_token: "7Hq2Kd9Rm4bV1nX" });

Inspecting attribution and session state:

// Returns the resolved attribution record for the current session
const attribution = window.FairShareSDK.getAttribution();

// Returns the current session token for cross-system correlation
const sessionToken = window.FairShareSDK.getSessionToken();

getSessionToken() throws when tracking has not initialized, initialization is still in progress, session creation failed, or the fluidShop identifier is invalid. Call it after initialization and handle the error when session state is optional. Flushing buffered events:

// Force all queued events to be sent immediately (useful before page unload)
await window.FairShareSDK.flushEvents();

// Queue delivery without waiting for the request to finish
window.FairShareSDK.flushEvents(false);

// Flush using the Beacon API — safe to call during the page unload event
window.FairShareSDK.flushEventsWithBeacon();

flushEvents() waits for delivery by default. Pass false when the caller should continue immediately.

Authentication

If your site has its own authentication system, you can pass a JWT to FairShare so the SDK associates cart and order activity with the authenticated user.

// Set the authenticated user's JWT
await window.FairShareSDK.setAuthentication("your-jwt-token");

Call setAuthentication() after your login flow completes. To clear the session — for example when the user logs out — call window.FairShareSDK.reset().

Get Started

Core Concepts

Guides

Migration guides

Website & Themes

FairShare SDK

Files SDK

FairShare Web Components

Cart Widget

When to Use

Usage

Attributes

JavaScript Settings Override

Lead Capture Widget

When to Use

Usage

Programmatic Lead Capture

Affiliate hydration

Media Widget

When to Use

Usage

Attributes

JavaScript methods

CSS Customization

Analytics and Events

Authentication

​Cart Widget

​When to Use

​Usage

​Attributes

​JavaScript Settings Override

​Lead Capture Widget

​When to Use

​Usage

​Programmatic Lead Capture

​Affiliate hydration

​Media Widget

​When to Use

​Usage

​Attributes

​JavaScript methods

​CSS Customization

​Analytics and Events

​Authentication

Cart Widget

When to Use

Usage

Attributes

JavaScript Settings Override

Lead Capture Widget

When to Use

Usage

Programmatic Lead Capture

Affiliate hydration

Media Widget

When to Use

Usage

Attributes

JavaScript methods

CSS Customization

Analytics and Events

Authentication