Skip to main content

UI components

Packages: @propeller-commerce/propeller-v2-react-ui and @propeller-commerce/propeller-v2-vue-ui

Ready-made commerce UI for React and Vue: product cards, grids, cart, checkout and account, plus a set of headless hooks (composables in Vue) that hold state and talk to the API but render nothing. Both libraries build on the SDK and the core layer, and ship a precompiled stylesheet, so you do not need Tailwind to use them.

Mount the provider​

Components and hooks read the SDK services from context. Build the client and services once (the SDK seam), then pass them to PropellerProvider at your app root.

// React
import { createClient } from '@propeller-commerce/propeller-sdk-v2';
import { PropellerProvider, createServices } from '@propeller-commerce/propeller-v2-react-ui';
import '@propeller-commerce/propeller-v2-react-ui/styles.css';

const graphqlClient = createClient({ endpoint: '/api/graphql' });
const services = createServices(graphqlClient);

// Pass the client and services plus your session scope. The provider derives
// the rest of the context (a PropellerInfra, including userMode) from these.
<PropellerProvider
  value={{
    graphqlClient,
    services,
    user,              // Contact | Customer | null
    companyId,         // number | undefined (active company, B2B)
    language: 'NL',
    currency: '€',
    includeTax: false,
    portalMode: 'open',
    shopMode: 'hybrid',
    configuration: {},
  }}
>
  {children}
</PropellerProvider>;

The value carries the client and services plus your session scope: the signed-in user, active company, language, currency, tax display, portal mode and shop mode. Recompute it when that state changes. Inside the provider, read the resolved context with useServices() (throws outside a provider) or usePropellerContext() (returns null outside a provider).

Vue follows the same idea: install the propellerVue plugin (or mount PropellerProvider) at the app root, then use the composables. See the Vue documentation site.

Entry points​

Each library exposes four import paths:

Import pathContentsRuntime
package rootcomponents, hooks, contexts, createServicesclient (carries "use client" in Next.js)
/purepresentational components only, safe in a Server Componentserver and client
/sharedcreateServices, formatters, helpers, types (no framework code)server and client
/styles.cssprecompiled stylesheetimport once at the root

In Next.js App Router, import createServices and the formatters from /shared, and pure components from /pure, when you render on the server, so you do not pull the whole client bundle across the boundary.

Components or hooks​

  • Components render commerce UI. Import one and render it inside the provider. Layout-heavy components such as ProductCard support a compound API (ProductCard.Image, ProductCard.Price and so on) so you control what renders and in what order.
  • Hooks (React) and composables (Vue) are headless: they hold state and call the API but render nothing. Use them to build your own UI, or to drive your own components. The set includes useCart, useAuth, useCheckout, useProductSearch, useProductInfo, useOrders, useFavorites, useMenu, useCompany, useAddress, useClusterConfigurator and the purchase-authorization hooks. useServices returns the services bundle from the provider.
import { useCart } from '@propeller-commerce/propeller-v2-react-ui';

const cart = useCart({ graphqlClient, user, language: 'NL' });

React and Vue parity​

The two libraries expose the same components and the same hook set (composables in Vue), so a storefront's structure carries across frameworks. Props and composable options are typed; read them in your editor or on the package's documentation site (React, Vue). The component reference lists what is available.

Build your own UI​

If you work in a framework without a Propeller UI library (Angular, Svelte, Web Components), use the SDK services and the formatters in the core layer directly, and treat the component reference as a spec for what to build.

See also​