Skip to main content

Customization

The UI components are built to be restyled and extended without forking. There are three styling surfaces and a few extension points.

Checked against propeller-v2-react-ui 0.32.0 and propeller-v2-vue-ui 0.31.1 on 28 October 2026.

Styling​

The component library ships a precompiled stylesheet. Import it once at your app root:

import '@propeller-commerce/propeller-v2-react-ui/styles.css';

You do not need Tailwind in your project. There are three override surfaces, from broadest to most specific:

  1. Theme tokens. The package declares CSS variables (--primary, --card, --border, --radius-container and more) at low specificity. Redeclare any of them in your own CSS and every component that resolves against it updates. Scope a token to a wrapper class to restyle only that subtree.

    :root {
      --primary: #ff7043;
      --card: #fafafa;
      --radius-container: 12px;
    }

  2. BEM hooks. Every styled element carries a BEM class alongside its utilities (.propeller-product-card, .propeller-product-card__price, .propeller-breadcrumbs__separator). Target these in your own CSS to override a specific element. No !important is needed.

  3. Per-instance className. Every component merges props.className into the classes on its root, so a one-off override is a regular prop. In the React library a utility you pass wins over the base utility it conflicts with (p-6 replaces the base p-4). Everything else is kept.

For the full token list and how the classes are named, see the styling guide (STYLING.md) shipped with each package.

Restructuring with the compound API​

Layout-heavy components expose a compound API so you can control what renders and in what order, instead of toggling show* props:

<ProductCard product={product}>
  <ProductCard.Image variant="grid" />
  <ProductCard.Name linkable />
  <ProductCard.Price />
  <ProductCard.AddToCart />
</ProductCard>

Omit the children and the component falls back to its default layout.

Extending components​

The React library has an extension API for replacing nested parts (price, stock, add to cart, badges, the whole card) with your own components without forking. See the extension API guide on GitHub.

Images​

To render every image through your framework's image component, such as next/image, pass it once as imgComponent. See Use your framework's image component.

Labels and translations​

Components accept a labels prop to override their UI strings, which is the basis for localization. Pass an empty string to hide a label; leave the key out to keep the default text. The Accelerator boilerplates wire a translation provider so strings resolve per language from one file per component. See Accelerator.

Callbacks​

Components surface callbacks at key moments (after add-to-cart, after register, on cart created) so you can run your own logic and store results in your own state. The available callbacks are part of each component's typed props.

See also​

Last updated on