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 providers​

The React library takes its setup through two providers. PropellerDepsProvider holds what is set up once for the whole app: the GraphQL client, the services built on it, the currency symbol and your configuration. PropellerProvider holds the session: the signed-in user, the active Company, the language, the tax display, the portal mode and the shop mode. Build the client and services once (the SDK seam), then mount both at your app root, with the session provider inside.

// React
import { createClient } from '@propeller-commerce/propeller-sdk-v2';
import {
  PropellerDepsProvider,
  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);

<PropellerDepsProvider
  value={{ graphqlClient, services, currency: '€', configuration: {} }}
>
  <PropellerProvider
    value={{
      user,              // Contact | Customer | null
      companyId,         // number | undefined (active company, B2B)
      language: 'NL',
      includeTax: false,
      portalMode: 'open',
      shopMode: 'hybrid',
    }}
  >
    {children}
  </PropellerProvider>
</PropellerDepsProvider>;

Create the client and services outside your components so they are built once. Recompute the session value when that state changes, for example after login or a company switch. A second PropellerProvider deeper in the tree replaces the session for that part of the page. Inside the providers, useServices() returns the services (it throws when PropellerDepsProvider is missing) and usePropellerContext() returns the client, services and session together (null when either provider is missing).

Vue splits the same two parts differently: install the propellerVue plugin once for the client, services, currency and configuration, then wrap the routed tree in the PropellerProvider component for the session.

// Vue
import { createApp } from 'vue';
import { createClient } from '@propeller-commerce/propeller-sdk-v2';
import { propellerVue, createServices } from '@propeller-commerce/propeller-v2-vue-ui';
import '@propeller-commerce/propeller-v2-vue-ui/styles.css';
import App from './App.vue';

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

createApp(App)
  .use(propellerVue, {
    graphqlClient,
    services: createServices(graphqlClient),
    currency: '€',
    configuration: {},
  })
  .mount('#app');
<!-- App.vue -->
<script setup lang="ts">
import { PropellerProvider } from '@propeller-commerce/propeller-v2-vue-ui';
// user and companyId come from your own session state.
</script>

<template>
  <PropellerProvider :user="user" :company-id="companyId" language="NL" :include-tax="false" portal-mode="open">
    <RouterView />
  </PropellerProvider>
</template>

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, usePropellerContext } from '@propeller-commerce/propeller-v2-react-ui';

function MiniCart() {
  // Hooks take the client and the session as options. Read both from the providers.
  const { graphqlClient, user, companyId, language } = usePropellerContext()!;
  const cart = useCart({ graphqlClient, user, companyId, language });
  // ...
}

Every hook takes an options object and its type is exported as Use<Name>Options, for example UseCartOptions. useCart needs the graphqlClient and the user. The rest is optional.

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, so your editor shows them inline. The component reference lists what is available and links every React component and every hook to its page on the package documentation sites (React, Vue). The Vue site documents the composables. For Vue component props, read the types.

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. The component reference works as a checklist of what to build.

See also​