mdxui

MarketplaceSite Specialization

Marketplace site type with buyers, sellers, products, and transactions

MarketplaceSite Specialization

The MarketplaceSite type is optimized for multi-sided marketplaces connecting buyers and sellers. It extends the base Site component with specialized components for product listings, seller profiles, shopping carts, checkout flows, and transaction management.

Naming Convention

MarketplaceSite follows the ${SiteType}${Component} pattern:

MarketplaceHeader = Header + search, cart, user menu
ProductGrid = Grid + marketplace products
ProductCard = Card + product preview
ProductDetail = Detail + full product view with purchase
SellerProfile = Profile + seller information and ratings
ShoppingCart = Cart + marketplace-specific features

All marketplace components are the base component enhanced with marketplace site-specific capabilities.

Type Definition

import type { MarketplaceSite } from 'mdxui'

interface MarketplaceSite extends BaseSite {
  type: 'marketplace'
  marketplace?: {
    payment?: string          // Payment provider (e.g., "stripe", "paypal")
    commission?: number       // Platform commission % (0-100)
    sellerDashboards?: boolean // Enable seller dashboards (default: true)
    buyerProtection?: boolean  // Enable buyer protection (default: true)
    reviews?: boolean         // Enable reviews/ratings (default: true)
  }
}

Usage

Basic Example

import { Site, MarketplaceHeader, ProductGrid, ShoppingCart } from '@mdxui/beacon'

<Site
  type="marketplace"
  name="Acme Marketplace"
  marketplace={{
    payment: "stripe",
    commission: 10,
    reviews: true
  }}
>
  <MarketplaceHeader />
  <ProductGrid products={products} />
  <ShoppingCart />
</Site>

With Seller Dashboards

<Site
  type="marketplace"
  name="Creator Marketplace"
  marketplace={{
    payment: "stripe",
    sellerDashboards: true,
    buyerProtection: true
  }}
>
  <SellerDashboard />
  <ProductGrid />
</Site>

Required Components

MarketplaceSite requires these specialized components:

MarketplaceHeader

Required: Yes

Marketplace header with search, cart, and user menu.

<MarketplaceHeader
  logo={<Logo />}
  search={true}
  cart={{
    items: 3,
    total: "$149.99"
  }}
  user={{
    name: "John Doe",
    avatar: "/avatars/john.jpg",
    role: "buyer"  // or "seller"
  }}
  navigation={[
    { label: "Browse", href: "/browse" },
    { label: "Sell", href: "/sell" },
    { label: "How it Works", href: "/how-it-works" }
  ]}
/>

ProductGrid

Required: Yes

Grid of marketplace product listings.

<ProductGrid
  products={[
    {
      id: "1",
      title: "Vintage Camera",
      price: 299.99,
      image: "/products/camera.jpg",
      seller: {
        name: "Jane's Shop",
        rating: 4.8,
        verified: true
      },
      rating: 4.5,
      reviews: 42,
      shipping: "Free shipping"
    }
  ]}
  layout="grid"
  itemsPerPage={24}
/>

ProductCard

Required: Yes

Individual product card in grid.

<ProductCard
  title="Vintage Camera"
  price={299.99}
  image="/products/camera.jpg"
  seller={{
    name: "Jane's Shop",
    rating: 4.8,
    verified: true
  }}
  rating={4.5}
  reviews={42}
  badge="Trending"
  shipping="Free shipping"
  href="/products/vintage-camera"
/>

ProductDetail

Required: Yes

Detailed product page with purchase options.

<ProductDetail
  product={{
    title: "Vintage Camera",
    description: "Professional 35mm film camera from the 1980s",
    price: 299.99,
    images: ["/img1.jpg", "/img2.jpg", "/img3.jpg"],
    seller: {
      name: "Jane's Shop",
      rating: 4.8,
      reviews: 120,
      verified: true,
      responseTime: "< 1 hour"
    },
    category: "Photography",
    condition: "Excellent",
    shipping: {
      cost: 0,
      estimatedDays: "3-5 business days"
    },
    returns: "30-day returns",
    rating: 4.5,
    reviews: reviewsData,
    stock: 1
  }}
  onAddToCart={() => {}}
  onBuyNow={() => {}}
/>

Optional Components

SellerProfile

Seller profile page with products and ratings.

<SellerProfile
  seller={{
    name: "Jane's Shop",
    avatar: "/avatars/jane.jpg",
    bio: "Curated vintage photography equipment",
    rating: 4.8,
    totalReviews: 120,
    totalSales: 450,
    joined: "2022-01-15",
    responseTime: "< 1 hour",
    verified: true,
    badges: ["Top Seller", "Fast Shipper"]
  }}
  products={sellerProducts}
  reviews={sellerReviews}
/>

ShoppingCart

Shopping cart with checkout.

<ShoppingCart
  items={[
    {
      id: "1",
      product: {
        title: "Vintage Camera",
        image: "/products/camera.jpg",
        seller: "Jane's Shop"
      },
      quantity: 1,
      price: 299.99
    }
  ]}
  subtotal={299.99}
  shipping={0}
  tax={24.00}
  total={323.99}
  onUpdateQuantity={(id, quantity) => {}}
  onRemove={(id) => {}}
  onCheckout={() => {}}
/>

Checkout

Multi-step checkout flow.

<Checkout
  steps={["Cart", "Shipping", "Payment", "Review"]}
  currentStep={1}
  cart={cartItems}
  onComplete={(order) => {
    // Process order
  }}
  payment={{
    provider: "stripe",
    publicKey: "pk_xxx"
  }}
  buyerProtection={true}
/>

Reviews

Product/seller reviews and ratings.

<Reviews
  target="product"  // or "seller"
  targetId="product-123"
  averageRating={4.5}
  totalReviews={42}
  distribution={{
    5: 28,
    4: 10,
    3: 2,
    2: 1,
    1: 1
  }}
  reviews={[
    {
      author: "John Doe",
      rating: 5,
      date: "2024-01-15",
      verified: true,
      text: "Exactly as described. Fast shipping!",
      helpful: 12
    }
  ]}
  allowSubmit={true}
  requirePurchase={true}
/>

SellerDashboard

Seller management dashboard.

<SellerDashboard
  stats={{
    totalSales: 450,
    revenue: "$45,230",
    activeListings: 32,
    pendingOrders: 3,
    averageRating: 4.8
  }}
  recentOrders={orders}
  products={products}
  analytics={analyticsData}
/>

Component Specializations

MarketplaceHeader

Base Header component + marketplace features.

// Enhanced with:
- Product search with filters
- Shopping cart icon with count
- User menu (buyer/seller toggle)
- Notifications (orders, messages)
- Categories dropdown

ProductGrid

Product listing with marketplace features.

// Enhanced with:
- Filter by price, category, seller
- Sort by relevance, price, rating
- Seller badges (verified, top seller)
- Wishlist/save functionality
- Quick view modal

ProductDetail

Product page with purchase flow.

// Enhanced with:
- Image gallery with zoom
- Seller information card
- Add to cart/Buy now buttons
- Shipping calculator
- Size/variant selector
- Related products
- Buyer protection badge

ShoppingCart

Cart with marketplace-specific features.

// Enhanced with:
- Multiple sellers in one cart
- Shipping estimates per seller
- Promo code support
- Save for later
- Recommended products
- Buyer protection info

Payment Integration

Stripe Connect

<Site
  type="marketplace"
  marketplace={{
    payment: "stripe",
    commission: 10
  }}
>
  {/* Automatically handles:
    - Seller account creation
    - Payment processing
    - Commission splits
    - Payouts to sellers
  */}
</Site>

Checkout Flow

<Checkout
  payment={{
    provider: "stripe",
    publicKey: "pk_xxx",
    commission: 10,
    applicationFee: true
  }}
  onPaymentComplete={(order) => {
    // Order placed
    // Platform takes 10% commission
    // Seller receives 90%
  }}
/>

Seller Features

Seller Onboarding

<SellerOnboarding
  steps={[
    "Create Profile",
    "Connect Payment",
    "Add Products",
    "Launch Store"
  ]}
  onComplete={(seller) => {
    // Seller account created
  }}
  paymentProvider="stripe"
/>

Product Management

<ProductManager
  seller={currentSeller}
  products={sellerProducts}
  onAddProduct={() => {}}
  onEditProduct={(id) => {}}
  onDeleteProduct={(id) => {}}
  analytics={{
    views: 1200,
    sales: 45,
    revenue: "$4,523"
  }}
/>

Order Management

<OrderManager
  seller={currentSeller}
  orders={sellerOrders}
  onUpdateStatus={(orderId, status) => {}}
  onAddTracking={(orderId, tracking) => {}}
  notifications={pendingOrders}
/>

Buyer Features

Wishlist

<Wishlist
  items={savedProducts}
  onRemove={(id) => {}}
  onAddToCart={(id) => {}}
  shareUrl="/wishlist/share/abc123"
/>

Order History

<OrderHistory
  orders={buyerOrders}
  onReorder={(orderId) => {}}
  onReview={(orderId, productId) => {}}
  onRequestReturn={(orderId) => {}}
/>

Buyer Protection

<BuyerProtection
  order={order}
  protectionPeriod={30}  // days
  onDispute={() => {}}
  onReturn={() => {}}
  policies={{
    returns: "30-day money back guarantee",
    shipping: "Full refund if not received",
    authenticity: "Verified seller program"
  }}
/>

Best Practices

Marketplace Strategy

  • Verify sellers: Badge verification program
  • Quality control: Review listings before publication
  • Fair fees: Competitive commission rates
  • Trust signals: Reviews, ratings, badges
  • Buyer protection: Clear return/refund policies
  • Communication: Enable buyer-seller messaging

Product Listings

  • Quality photos: Multiple high-res images
  • Detailed descriptions: Complete product information
  • Accurate pricing: Include all fees upfront
  • Clear shipping: Costs and delivery estimates
  • Honest condition: Accurate product condition
  • Categories: Proper categorization

Trust and Safety

  • Seller verification: ID and payment verification
  • Fraud detection: Monitor suspicious activity
  • Dispute resolution: Fair mediation process
  • Secure payments: PCI-compliant processing
  • Data protection: Encrypt sensitive information

Real-World Example

Complete marketplace site:

import {
  Site,
  MarketplaceHeader,
  ProductGrid,
  ProductDetail,
  SellerProfile,
  ShoppingCart,
  Checkout,
  Reviews,
  SellerDashboard
} from '@mdxui/beacon'

<Site
  type="marketplace"
  name="Vintage Market"
  domain="vintagemarket.com"
  marketplace={{
    payment: "stripe",
    commission: 10,
    sellerDashboards: true,
    buyerProtection: true,
    reviews: true
  }}
>
  <MarketplaceHeader
    logo={<Logo />}
    search={true}
    cart={cart}
    user={currentUser}
    navigation={mainNav}
  />

  {/* Browse Page */}
  <div className="marketplace-layout">
    <FilterPanel
      filters={productFilters}
      selected={activeFilters}
    />

    <main>
      <ProductGrid
        products={products}
        layout="grid"
        itemsPerPage={24}
        sortOptions={sortOptions}
      />
    </main>
  </div>

  {/* Product Detail */}
  <ProductDetail
    product={currentProduct}
    onAddToCart={handleAddToCart}
    onBuyNow={handleBuyNow}
  >
    <Reviews
      target="product"
      targetId={currentProduct.id}
      reviews={productReviews}
      allowSubmit={hasPurchased}
    />

    <SellerCard
      seller={currentProduct.seller}
      href={`/sellers/${currentProduct.seller.id}`}
    />

    <RelatedProducts
      products={relatedProducts}
      algorithm="category"
    />
  </ProductDetail>

  {/* Seller Profile */}
  <SellerProfile
    seller={currentSeller}
    products={sellerProducts}
    reviews={sellerReviews}
  />

  {/* Shopping Cart */}
  <ShoppingCart
    items={cartItems}
    onUpdateQuantity={handleUpdateQuantity}
    onRemove={handleRemove}
    onCheckout={() => navigate('/checkout')}
  />

  {/* Checkout */}
  <Checkout
    steps={["Cart", "Shipping", "Payment", "Review"]}
    cart={cartItems}
    payment={{
      provider: "stripe",
      publicKey: stripeKey
    }}
    onComplete={handleOrderComplete}
    buyerProtection={true}
  />

  {/* Seller Dashboard */}
  <SellerDashboard
    seller={currentSeller}
    stats={sellerStats}
    recentOrders={recentOrders}
    products={sellerProducts}
    analytics={sellerAnalytics}
  >
    <ProductManager
      products={sellerProducts}
      onAddProduct={handleAddProduct}
    />

    <OrderManager
      orders={sellerOrders}
      onUpdateStatus={handleUpdateStatus}
    />
  </SellerDashboard>
</Site>

TypeScript

Full type definition:

import { z } from 'zod'
import { BaseSiteSchema } from 'mdxui/zod'

export const MarketplaceSiteSchema = BaseSiteSchema.extend({
  type: z.literal('marketplace'),
  marketplace: z.object({
    payment: z.string().optional(),
    commission: z.number().min(0).max(100).optional(),
    sellerDashboards: z.boolean().default(true),
    buyerProtection: z.boolean().default(true),
    reviews: z.boolean().default(true),
  }).optional(),
})

export type MarketplaceSite = z.infer<typeof MarketplaceSiteSchema>

DirectorySite Specialization

Directory site type with listings, search, filters, and map views

APISite Specialization

API documentation site type with reference docs, playground, and code samples

On this page

MarketplaceSite SpecializationNaming ConventionType DefinitionUsageBasic ExampleWith Seller DashboardsRequired ComponentsMarketplaceHeaderProductGridProductCardProductDetailOptional ComponentsSellerProfileShoppingCartCheckoutReviewsSellerDashboardComponent SpecializationsMarketplaceHeaderProductGridProductDetailShoppingCartPayment IntegrationStripe ConnectCheckout FlowSeller FeaturesSeller OnboardingProduct ManagementOrder ManagementBuyer FeaturesWishlistOrder HistoryBuyer ProtectionBest PracticesMarketplace StrategyProduct ListingsTrust and SafetyReal-World ExampleTypeScriptRelated Documentation