UI Components

Beta

The Storefront SDK is in beta. Content in this section may be updated as the SDK evolves.

Packages: @propeller/ui-react (npm), @propeller/ui-vue (npm, coming)

Pre-built e-commerce components that use the SDK internally. Install via npm. Use in any React or Vue project without the Accelerator.

This is Layer 2 of the Storefront SDK. It builds on Layer 1 (SDK Services) and is used by Layer 3 (Accelerator).

How they're built

Components are authored in Mitosis, a framework-agnostic component format. From a single source file (.lite.tsx), Propeller compiles to both React and Vue outputs. This ensures identical behavior across frameworks.

Design principle: SDK-only

UI components talk to Propeller SDK services only. They have no CMS dependency. A ProductCard fetches product data from the SDK. A ProductGrid fetches category data from the SDK. An AddToCart component creates and manages carts through the SDK.

CMS content is not baked into the components. Instead, components expose callbacks and events where you can inject CMS content, custom logic or framework-specific routing. This keeps the components portable across any project, regardless of which CMS (or no CMS) you use.

Usage example

import { ProductCard } from '@propeller/ui-react';
import { graphqlClient } from './lib/api';

<ProductCard
  product={product}
  graphqlClient={graphqlClient}
  user={authState.user}
  cartId={cart?.cartId}
  configuration={config}
  showModal={true}
  onProductClick={(p) => router.push(`/product/${p.productId}`)}
  afterAddToCart={(cart) => saveCart(cart)}
/>

The onProductClick callback is where you handle routing. The component does not care whether you use Next.js router.push, Vue Router or plain window.location. Same for afterAddToCart: you decide what happens after an item is added.

Common component properties

Components receive data and configuration through properties. The most common properties across components are:

Property	Description
graphqlClient	A GraphQL client instance. The SDK provides a default client, or you can implement your own.
user	The current user object from your application state. Components do not manage user state themselves.
product	The product object (needed for product ID, pricing and other product-level behavior). Used by product-level components like ProductCard and AddToCart.
configuration	A reference to the global route config file that controls URL patterns and base settings.

Not every component uses the same set of properties. For example, ProductGrid takes a categoryId and graphqlClient but does not require a product prop. The component documentation specifies which properties each component accepts.

Callback pattern

Components do not own or dictate application state. They follow a callback pattern:

1. A component performs an action (add to cart, login, register)
2. The component calls a callback with the result (the new cart, the user object)
3. Your application stores the result however you choose

This means you are free to use any state management approach: React Context, Zustand, Redux or plain state. See Customization for more on callbacks and override patterns.

Component inventory

Category	Components
Catalog	ProductCard, ProductGrid, ProductInfo, ProductGallery, ProductPrice, ProductSpecifications, ProductTabs, ProductDescription, ProductShortDescription, ProductDownloads, ProductVideos, ProductBulkPrices, ClusterCard, GridFilters, GridToolbar, GridTitle, GridPagination, CategoryDescription, CategoryShortDescription
Cart and checkout	AddToCart
Navigation	Menu, Breadcrumbs
Account	OrderList

Where CMS content fits

Components do not include CMS content, but many offer natural injection points via callbacks:

Component	CMS injection point	What you'd inject
ProductGrid	onCategoryChange callback	A category banner image from your CMS
Registration form	Before/after registration events	Custom terms and conditions from CMS, post-registration CMS content
Header	Logo/navigation props	Logo and nav links managed in your CMS
Footer	Content props	Footer columns and links from your CMS

The Accelerator includes working examples of these patterns using Strapi.

Stack-agnostic component documentation

Coming soon

Individual component reference pages (properties, callbacks and usage examples) are being added to the API Reference section.

Every UI component is also documented at a conceptual level, independent of React or Vue. This documentation describes what the component does, its properties, events and SDK usage. It serves two purposes:

1. Understanding — you can read the conceptual docs to understand what a component does before looking at framework-specific code.
2. Building your own — if you work in a framework Propeller does not provide components for (Angular, Svelte, Web Components, etc.), the conceptual documentation serves as a complete spec to build your own implementation.

Using component documentation for custom implementations

The stack-agnostic documentation can be used as input for AI-assisted component generation. Partners have demonstrated generating working Next.js and Web Components implementations from the conceptual component descriptions, producing functional prototypes in hours rather than days.

This is particularly useful for:

• Pre-sales — rapidly prototype a storefront to demonstrate what is possible, without committing to a framework
• Non-standard stacks — when the partner's project uses a framework Propeller does not provide components for, the documentation serves as a complete spec
• Starting point, not end state — AI-generated components are useful as accelerators, but production implementations require manual work on deep linking, query parameter handling, URL-friendly filters and edge cases

The component documentation also enables non-technical conversations. Because it describes interaction concepts rather than code, it can be discussed with marketing and product teams.

Rendering approach

Components are client-side rendered ('use client' in Next.js). The Accelerator runs on Next.js, which supports server-side rendering for initial page loads and static generation at the page level, but the UI components themselves execute on the client.

Component nesting and pass-through properties

When a child component (like AddToCart) is embedded in a parent component (like ProductCard), the parent exposes pass-through properties. This means you provide AddToCart properties directly on ProductCard, and ProductCard forwards them to its embedded AddToCart.

The component documentation for each parent lists which properties are its own and which are forwarded to child components.

See also

• SDK Services — the typed services that components use internally
• Accelerator — the full app that uses these components
• Customization — callbacks, pass-through properties and override patterns
• B2B Capabilities — portal modes and clusters in component context