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.

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 appends props.className on its root, so a one-off override is a regular prop. The class adds to the base classes rather than replacing them.

For the full token list and the BEM hook catalog, see the STYLING.md shipped with the 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 component library ships a partner extension API for customizing nested parts (price, stock, add-to-cart, the whole card) without forking. See the Partner extension API section in the package README, or the documentation site.

Labels and translations​

Components accept a labels prop to override their UI strings, which is the basis for localization. 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​