Skip to main content

​
@shoppex/ui

A collection of React components and hooks with built-in SDK integration for building Shoppex storefronts quickly.
Developer-First Approach: These components are designed to be used with AI assistance. Simply describe what you want, and AI can compose these building blocks into custom themes.

​
Why @shoppex/ui?

SDK Integration

Components connect to @shoppex/sdk automatically. Cart, checkout, and store data just work.

Customizable

Built with Tailwind CSS and CSS variables. Easy to theme and extend.

Production Ready

Accessibility, keyboard navigation, loading states, and error handling built-in.

TypeScript

Full type safety with exported interfaces for all props and return values.

​
Installation

npm install @shoppex/ui @shoppex/sdk

​
Quick Example

import { shoppex } from '@shoppex/sdk';
import {
  useStore,
  useCart,
  Hero,
  ProductGrid,
  CartDrawer
} from '@shoppex/ui';
import { useState } from 'react';

// Initialize SDK
shoppex.init('your-store-slug');

function App() {
  const { store, products, isLoading } = useStore();
  const { totalQuantity } = useCart();
  const [cartOpen, setCartOpen] = useState(false);

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      {/* Header with cart button */}
      <header>
        <button onClick={() => setCartOpen(true)}>
          Cart ({totalQuantity})
        </button>
      </header>

      {/* Hero section */}
      <Hero store={store} products={products} />

      {/* Product grid */}
      <ProductGrid products={products} />

      {/* Cart drawer */}
      <CartDrawer
        isOpen={cartOpen}
        onClose={() => setCartOpen(false)}
      />
    </div>
  );
}

​
What’s Included

​
Primitives (Hooks)

Headless hooks for state management and SDK integration.
HookDescription
useCart()Cart state with add/remove/update operations
useCartItem()Cart state for a specific product
useStore()Fetch store, products, and groups
useStoreSettings()Store configuration flags
useSearch()Product search with debouncing
useProductFilter()Filter and sort products
useCheckout()Checkout flow and coupon validation
usePrice()Price formatting

​
Components

Pre-styled UI components with SDK integration.
ComponentDescription
ProductCardProduct card with image, price, add-to-cart
AddToCartButtonSmart button with quantity controls
CartDrawerSlide-over cart sidebar
CheckoutModalEmail collection modal
SearchCommandCmd+K search palette
PriceDisplayFormatted price display

​
Blocks

Larger page sections for common storefront layouts.
BlockDescription
HeroStore hero with logo, title, stats
ProductGridResponsive product grid with filters
WhyChooseUsFeatures bento grid
FAQAccordion FAQ section
FooterStore footer with links

​
Styling

Components use CSS variables for theming. Add these to your CSS: 
:root {
  /* Core colors */
  --color-background: #09090b;
  --color-foreground: #fafafa;
  --color-card: #18181b;
  --color-primary: #7c3aed;
  --color-primary-foreground: #ffffff;

  /* Muted colors */
  --color-muted: #27272a;
  --color-muted-foreground: #a1a1aa;

  /* Border */
  --color-border: #27272a;

  /* Destructive (errors) */
  --color-destructive: #ef4444;
}
Components work great with Tailwind CSS. The class names follow Tailwind conventions and can be customized via the className prop on most components.