@couture/sizing-agent

AI-powered sizing recommendation component for Next.js applications. Helps customers find their perfect size through an intelligent questionnaire.

Features

• 🎯 Accurate Recommendations - Multi-factor algorithm considers height, weight, body type, and fit preferences
• 👕 Product-Aware - Automatically adapts to upper-body (hoodies, shirts) or lower-body (pants) products
• 📱 Responsive - Works seamlessly on mobile and desktop
• ⚡ Zero Config - Drop-in component, works out of the box

Prerequisites

This component requires Tailwind CSS to be installed and configured in your Next.js project.

If you don't have Tailwind CSS set up:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Configure your tailwind.config.js:

module.exports = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@couture/sizing-agent/**/*.{js,ts,jsx,tsx}', 
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Add Tailwind directives to your global CSS:

@tailwind base;
@tailwind components;
@tailwind utilities;

Installation

npm install @couture/sizing-agent

Requirements: Next.js 14+ with App Router

Quick Start

'use client'

import { SizingAgent } from '@couture/sizing-agent'
import { useState } from 'react'

export default function ProductPage() {
  const [showAgent, setShowAgent] = useState(false)
  const [size, setSize] = useState('')

  return (
    <div>
      <button onClick={() => setShowAgent(true)}>
        What's My Size?
      </button>

      {showAgent && (
        <SizingAgent
          productName="Heavyweight Hoodie"
          productSizes={["S", "M", "L", "XL"]}
          productDimensions={[
            { size: "S", chest: 26, length: 26.8, sleeve: 21.1, shoulder: 25.6 },
            { size: "M", chest: 26.8, length: 27.6, sleeve: 21.5, shoulder: 26.4 },
            { size: "L", chest: 27.6, length: 28.4, sleeve: 21.9, shoulder: 27.2 },
            { size: "XL", chest: 28.4, length: 29.1, sleeve: 22.2, shoulder: 27.9 },
          ]}
          fitFactor={5}
          onClose={() => setShowAgent(false)}
          onRecommendSize={(recommendedSize) => {
            setSize(recommendedSize)
            setShowAgent(false)
          }}
        />
      )}
    </div>
  )
}

API Reference

SizingAgent Component

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | productName | string | ✅ | - | Name of the product (e.g., "Heavyweight Hoodie") | | productSizes | string[] | ✅ | - | Available sizes (e.g., ["S", "M", "L", "XL"]) | | productDimensions | ProductDimensions[] | ✅ | - | Measurements for each size | | fitFactor | number | ❌ | 3 | Garment's inherent fit (1=tight, 3=regular, 5=baggy) | | onClose | () => void | ✅ | - | Callback when modal is closed | | onRecommendSize | (size: string) => void | ✅ | - | Callback with recommended size | | customStyles | object | ❌ | {} | Custom styling options | | measurementImages | object | ❌ | {} | Custom measurement reference images |

ProductDimensions Interface

interface ProductDimensions {
  size: string          // Size label (e.g., "M")
  chest?: number        // Half-chest width in inches
  length: number        // Garment length in inches
  sleeve?: number       // Sleeve length in inches
  shoulder?: number     // Shoulder width in inches
  waist?: number        // Waist measurement in inches (for pants)
  inseam?: number       // Inseam length in inches (for pants)
}

Custom Styles

customStyles={{
  primaryColor: "#FF6B6B",      // Brand color for buttons/progress
  fontFamily: "Inter, sans-serif", // Custom font
  borderRadius: "8px"            // Border radius for elements
}}

Custom Measurement Images

measurementImages={{
  chest: "/images/chest-guide.jpg",
  waist: "/images/waist-guide.jpg",
  shoulder: "/images/shoulder-guide.jpg",
  hip: "/images/hip-guide.jpg",
  pantLength: "/images/pant-length-guide.jpg"
}}

Advanced Usage

Using Core Functions Directly

For headless implementations or custom UIs:

import { calculateRecommendedSize, calculateTargetMeasurements } from '@couture/sizing-agent'

const userMeasurements = {
  height: { feet: 5, inches: 10 },
  weight: 160,
  gender: "Male",
  fitPreference: "Regular Fit",
  usualSize: "M",
  chest: "Normal/Average",
  stomach: "Normal/Average",
  seat: "",
  torsoLength: "",
  legLength: "",
  shoulders: "Normal/Average",
  preferMetric: false
}

const recommendedSize = calculateRecommendedSize(
  userMeasurements,
  ["S", "M", "L", "XL"],
  productDimensions,
  3 // fitFactor
)

console.log('Recommended:', recommendedSize) // "M"

API Integration Example

// Server-side sizing API endpoint
import { calculateRecommendedSize } from '@couture/sizing-agent'

export async function POST(request: Request) {
  const { userMeasurements, productData } = await request.json()
  
  const recommendedSize = calculateRecommendedSize(
    userMeasurements,
    productData.sizes,
    productData.dimensions,
    productData.fitFactor
  )
  
  return Response.json({ recommendedSize })
}

Shopify Integration

Liquid Template

<!-- Add button to product page -->
<button id="sizing-agent-trigger" class="btn">
  What's My Size?
</button>

<!-- Add container for React app -->
<div id="sizing-agent-root"></div>

<!-- Load React and component -->
<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="https://unpkg.com/@couture/sizing-agent@latest/dist/index.umd.js"></script>

<script>
  const productDimensions = {{ product.metafields.custom.dimensions | json }};
  
  document.getElementById('sizing-agent-trigger').addEventListener('click', () => {
    const root = document.getElementById('sizing-agent-root');
    
    ReactDOM.render(
      React.createElement(SizingAgent.default, {
        productName: "{{ product.title }}",
        productSizes: {{ product.variants | map: 'option1' | uniq | json }},
        productDimensions: productDimensions,
        fitFactor: {{ product.metafields.custom.fit_factor | default: 3 }},
        onClose: () => ReactDOM.unmountComponentAtNode(root),
        onRecommendSize: (size) => {
          // Update variant selector
          document.querySelector('[name="Size"]').value = size;
          ReactDOM.unmountComponentAtNode(root);
        }
      }),
      root
    );
  });
</script>

Product Dimension Guidelines

Upper Body Products (Hoodies, Shirts, Crewnecks)

Measure in inches:

• Chest: Half-width across chest (armpit to armpit)
• Length: From shoulder seam to bottom hem
• Sleeve: From shoulder seam to cuff
• Shoulder: Across shoulder seams

Lower Body Products (Pants, Sweatpants)

Measure in inches:

• Waist: Full waist circumference (or half-width × 2)
• Length: From waistband to hem
• Inseam: From crotch to hem

Fit Factor Guide

• 1-2: Tight/Fitted garments (compression wear, slim fit tees)
• 3: Regular fit (standard hoodies, regular tees)
• 4-5: Relaxed/Oversized (baggy hoodies, oversized sweatshirts)

How It Works

The sizing agent uses a sophisticated multi-factor algorithm:

1. User Profile Analysis - Height, weight, gender, and body attributes
2. Target Calculation - Computes ideal measurements using gender-neutral reference points
3. Adjustment Layers:
   • Body attributes (chest, shoulders, torso length, etc.)
   • Garment fit factor (inherent fit style)
   • User fit preference (how they like clothes to fit)
4. Multi-Factor Scoring - Weighted scoring system:
   • Length: 5× weight (most critical)
   • Chest/Waist: 2× weight
   • Shoulders: 1× weight
   • Sleeves: 0.5× weight
   • Usual size bonus: +20-30 points
5. Conservative Adjustment - Moderates extreme recommendations toward usual size

TypeScript Support

Full type definitions included:

import type { 
  SizingAgentProps, 
  ProductDimensions, 
  UserMeasurements,
  SizeScore 
} from '@couture/sizing-agent'

Browser Support

• Chrome/Edge (latest 2 versions)
• Firefox (latest 2 versions)
• Safari (latest 2 versions)
• Mobile browsers (iOS Safari, Chrome Mobile)

License

MIT

Support

For issues, questions, or feature requests, please open an issue on GitHub or contact [email protected]

Made with ❤️ by Couture