Selection Guide UI Plugin

Embed the Selection Guide UI widget on your product detail pages to show size-fit guidance, confidence scores, and customer feedback summaries.

The Selection Guide UI is a lightweight, zero-dependency JavaScript widget that renders size recommendations directly on your product detail pages. It fetches data from the Size Recommender API and displays fit category, a visual scale, confidence score, and an AI-generated customer feedback summary. The widget also supports localized default strings, configurable fallbacks for missing data, and per-section visibility controls.

This is an open-source reference implementation in the parcelLab Embedded UI Snippets repository. Use it as-is, or as a starting point for building your own custom integration against the API.

Sample with short info text

neutral color, comfortable spacing, inline display

colored, compact spacing, card display

Sample with longer info text

neutral color, compact spacing, inline display

colored, compact spacing, card display

Missing data

notFoundMode: 'true-to-size' — shows default fit info

notFoundMode: 'empty' — shows missing data notice

Installation

The widget ships as a standalone JavaScript bundle. No build tools or package managers are required.

Available bundle files:

https://cdn.parcellab.com/js/selection-guide-ui/v1/size-recommender.iife.js
https://cdn.parcellab.com/js/selection-guide-ui/v1/size-recommender.esm.js

Add a single <script> tag to your page. The IIFE build auto-initializes any element with the data-size-recommender attribute:

<div
  data-size-recommender
  data-account-id="YOUR_ACCOUNT_ID"
  data-product-id="YOUR_PRODUCT_ID"
  data-not-found-mode="true-to-size"
></div>

<script
  src="https://cdn.parcellab.com/js/selection-guide-ui/v1/size-recommender.iife.js"
  defer
></script>

For more control, use the JavaScript API to initialize the widget programmatically:

<div id="size-recommender"></div>

<script src="https://cdn.parcellab.com/js/selection-guide-ui/v1/size-recommender.iife.js"></script>
<script>
  const widget = window.SizeRecommender.init({
    target: '#size-recommender',
    accountId: 'YOUR_ACCOUNT_ID',
    productId: 'YOUR_PRODUCT_ID',
    notFoundMode: 'true-to-size'
  });
</script>

If you want to load the ESM build directly in the browser, import it from the CDN:

<div id="size-recommender"></div>

<script type="module">
  import { init } from 'https://cdn.parcellab.com/js/selection-guide-ui/v1/size-recommender.esm.js';

  const widget = init({
    target: '#size-recommender',
    accountId: 'YOUR_ACCOUNT_ID',
    productId: 'YOUR_PRODUCT_ID',
    notFoundMode: 'true-to-size'
  });
</script>

Live demo

Try the interactive demo to preview different configurations and copy embed code:

Selection Guide UI — Dev Democdn.parcellab.com

The demo page is maintained in the Selection Guide UI module in the parcelLab Embedded UI Snippets repository.

Configuration

All options can be set via JavaScript or as HTML data-* attributes.

Option

Data attribute

Type

Default

Description

target

—

string | HTMLElement

—

Required (JS only). CSS selector or DOM element to mount the widget.

accountId

data-account-id

number | string

—

Required. Your parcelLab account ID.

productId

data-product-id

string

—

Required. Product identifier passed to the API.

articleName

data-article-name

string

—

Legacy alias for productId. Still accepted for backwards compatibility.

notFoundMode

data-not-found-mode

'empty' | 'true-to-size' | 'hidden'

'true-to-size'

Behavior when no recommendation exists (see 404 handling).

appearance

data-appearance

'neutral' | 'colored' | 'alert'

'colored'

Visual style. neutral is grayscale, colored uses a gradient track, and alert uses stronger fit-sensitive colors.

density

data-density

'compact' | 'comfortable'

'comfortable'

Spacing. compact is ideal for tighter PDP layouts.

surface

data-surface

'subtle' | 'plain'

'plain'

subtle renders a light card background; plain renders inline.

locale

data-locale

string

'en'

Locale for default message strings. Supported locales: en, de, fr, it, es.

showPill

data-show-pill

boolean

true

Show or hide the fit category pill badge.

showScale

data-show-scale

boolean

true

Show or hide the fit scale.

showRecommendation

data-show-recommendation

boolean

true

Show or hide the recommendation callout block.

showSummary

data-show-summary

boolean

true

Show or hide the AI-generated summary inside the recommendation block.

messages

data-messages

Partial<WidgetMessages>

—

Override any default text (title, labels, headings). Pass as JSON string in HTML.

theme

data-theme

Partial<WidgetTheme>

—

Override CSS tokens (colors, radius). Pass as JSON string in HTML.

className

data-class-name

string

—

Extra CSS classes added to the root element.

apiBaseUrl

data-api-base-url

string

'https://api.parcellab.com'

Override the API base URL (for testing or staging).

The legacy articleName / data-article-name option is still accepted as an alias for productId, but productId is recommended for new integrations.

HTML attribute example

When using the auto-initializing script tag, configure the widget directly on the target element:

<div
  data-size-recommender
  data-account-id="YOUR_ACCOUNT_ID"
  data-product-id="YOUR_PRODUCT_ID"
  data-not-found-mode="hidden"
  data-appearance="alert"
  data-density="comfortable"
  data-surface="plain"
  data-locale="de"
  data-show-summary="false"
></div>

<script
  src="https://cdn.parcellab.com/js/selection-guide-ui/v1/size-recommender.iife.js"
  defer
></script>

Messages customization

Override any text label using the messages option:

window.SizeRecommender.init({
  target: '#size-recommender',
  accountId: 'YOUR_ACCOUNT_ID',
  productId: 'YOUR_PRODUCT_ID',
  messages: {
    title: 'How It Fits',
    recommendationHeadingSmall: 'Consider sizing up',
    recommendationHeadingLarge: 'Consider sizing down',
    recommendationHeadingTrue: 'Should fit as expected',
    confidenceText: '{value}% confident based on store feedback'
  }
});

Theme customization

Override visual tokens to match your brand:

window.SizeRecommender.init({
  target: '#size-recommender',
  accountId: 'YOUR_ACCOUNT_ID',
  productId: 'YOUR_PRODUCT_ID',
  theme: {
    backgroundColor: '#f6f6f6',
    textColor: '#222222',
    mutedTextColor: '#666666',
    borderColor: '#e4e4e4',
    radius: '12px'
  }
});

Appearance modes

neutral — grayscale style that blends with most page designs.
colored (default) — uses a gradient on the fit scale and tinted badge for a more visual indication.
alert — uses stronger fit-sensitive colors to make likely size mismatch more prominent.

Both modes are shown in the comparison table above.

404 handling

When the API returns no recommendation for a product, the widget supports three modes:

true-to-size (default) — shows a "likely true to size" fallback without confidence or AI summary. Useful as a safe default assumption.
empty — shows a "no data available" message.
hidden — hides the widget entirely until valid data is returned.

If you use hidden, the widget becomes visible again automatically when a later update() or refresh() call receives valid data.

The true-to-size and empty modes are shown in the first row of the comparison table above.

The init() call returns a widget instance with methods for dynamic updates:

Method

Description

widget.update(config)

Update configuration (e.g., switch product) and re-fetch. Cancels any in-flight request.

widget.refresh()

Re-fetch the recommendation with current configuration.

widget.destroy()

Remove the widget from the DOM and clean up event listeners.

Example: switching products

On single-page applications (SPAs) or pages with product variant selectors, update the widget when the product changes:

const widget = window.SizeRecommender.init({
  target: '#size-recommender',
  accountId: 'YOUR_ACCOUNT_ID',
  productId: 'Original Product'
});

// When the user selects a different variant:
document.querySelector('#variant-select').addEventListener('change', (e) => {
  widget.update({ productId: e.target.value });
});

Styling

The widget renders in the light DOM (not Shadow DOM), so your page's typography inherits naturally. You can target the widget's elements directly with CSS.

CSS classes

The widget uses BEM-style class names under the .pl-size-recommender namespace. All classes are applied in the light DOM, so you can target them directly from your stylesheet.

Root modifier classes

These are applied to the root element and reflect the current configuration and state:

Class

Description

.pl-size-recommender

Root element (always present)

.pl-size-recommender--neutral

Neutral (grayscale) appearance

.pl-size-recommender--colored

Colored appearance with gradient track

.pl-size-recommender--alert

Alert appearance with stronger fit-sensitive colors

.pl-size-recommender--density-compact

Compact spacing

.pl-size-recommender--density-comfortable

Comfortable spacing

.pl-size-recommender--surface-subtle

Card background with border

.pl-size-recommender--surface-plain

Inline, no card background

.pl-size-recommender--state-loading

Widget is loading data

.pl-size-recommender--state-ready

Data loaded successfully

.pl-size-recommender--state-fallback-true

Showing true-to-size fallback (no data)

.pl-size-recommender--state-empty

Showing empty/no-data state

.pl-size-recommender--state-error

API error occurred

.pl-size-recommender--state-hidden

Widget is hidden because notFoundMode is hidden

.pl-size-recommender--fit-small

Product runs small

.pl-size-recommender--fit-true

Product is true to size

.pl-size-recommender--fit-large

Product runs large

.pl-size-recommender--fit-unknown

Fit category unknown

Element classes

These target individual parts of the widget:

Class

Description

.pl-size-recommender__header

Header row containing title and pill

.pl-size-recommender__title

"How It Fits" heading

.pl-size-recommender__pill

Fit category badge (e.g., "True to size")

.pl-size-recommender__scale

Scale container (labels + track)

.pl-size-recommender__scale-labels

"Runs Small / True to Size / Runs Large" labels

.pl-size-recommender__track

The horizontal fit bar

.pl-size-recommender__marker

Position dot on the track

.pl-size-recommender__recommendation

Recommendation callout card

.pl-size-recommender__recommendation-header

Header row inside the recommendation

.pl-size-recommender__recommendation-icon

Fit direction icon (arrow up/down/dash)

.pl-size-recommender__recommendation-title

Recommendation heading (e.g., "Consider sizing up")

.pl-size-recommender__recommendation-meta

Confidence text (e.g., "89% confident based on real customer feedback")

.pl-size-recommender__recommendation-summary

AI-generated customer feedback summary

Hiding elements with CSS

If you want to hide specific parts of the widget, prefer the built-in visibility options (showPill, showScale, showRecommendation, showSummary). You can also use CSS and display: none on the relevant class:

/* Hide the confidence score */
.pl-size-recommender__recommendation-meta {
  display: none;
}

/* Hide the AI summary text */
.pl-size-recommender__recommendation-summary {
  display: none;
}

/* Hide the fit category pill badge */
.pl-size-recommender__pill {
  display: none;
}

/* Hide the entire scale bar */
.pl-size-recommender__scale {
  display: none;
}

/* Hide the widget entirely when it enters the hidden state */
.pl-size-recommender--state-hidden {
  display: none;
}

CSS variables

Override these on .pl-size-recommender or any ancestor element:

Variable

Description

--plsr-background

Widget background color

--plsr-recommendation-background

Recommendation callout background

--plsr-border

Border color

--plsr-text

Primary text color

--plsr-muted-text

Secondary text color

--plsr-accent

Accent color for highlights

--plsr-badge-background

Fit category badge background

--plsr-badge-text

Fit category badge text color

--plsr-track

Scale track color (neutral mode)

--plsr-track-start / --plsr-track-end

Track gradient colors (colored and alert modes)

--plsr-radius

Border radius

Example: custom styling

.pl-size-recommender {
  --plsr-background: #fafafa;
  --plsr-text: #1a1a1a;
  --plsr-accent: #3D3AD3;
  --plsr-radius: 16px;
  font-family: 'Your Brand Font', sans-serif;
}

Building your own integration

This widget is an open-source reference implementation. If you need deeper customization beyond what the configuration options offer, you have several paths:

Use the API directly — Call the Size Recommender API from your own frontend code and render the response however you like.
Fork the embedded UI snippets repository — Start from the Selection Guide UI module and customize the rendering, styling, and behavior to match your exact requirements.
Use as a library — Import the ESM build and override messages, theme, and CSS to fit your design system.

The source code is organized into clear modules (API client, config resolution, model transformation, rendering) that you can reference or reuse.

Source code

Repository: github.com/parcelLab/parcellab-embedded-ui-snippets/tree/main/packages/selection-guide-ui
Live demo: cdn.parcellab.com/playground/selection-guide-ui
License: MIT

PreviousSize Recommender API NextAgents

Last updated 2 months ago

Was this helpful?

Installation

Live demo

Configuration

HTML attribute example

Messages customization

Theme customization

Appearance modes

404 handling

Widget instance API

Example: switching products

Styling

CSS classes

Root modifier classes

Element classes

Hiding elements with CSS

CSS variables

Example: custom styling

Building your own integration

Source code