@commercelayer/react-components v4.13.0

Commerce Layer React Components

A collection of reusable React components that makes it super fast and simple to build your own custom commerce UI, leveraging Commerce Layer API.

What is Commerce Layer?

Commerce Layer is a headless platform that lets you easily build enterprise-grade ecommerce into any website, by using the language, CMS, and tools you already master and love.

Getting started

To get started with Commerce Layer React Components you need to install them and then get the credentials that will allow you to perform the API calls they wrap.

• Installation
• Authentication
• Import

Installation

Commerce Layer React Components are available as an npm package:

// npm
npm install @commercelayer/react-components

// yarn
yarn add @commercelayer/react-components

Authentication

All requests to Commerce Layer API must be authenticated with an OAuth2 bearer token. Hence, to use these components, you need to get a valid access token. Once you got it, you can pass it as prop — together with the endpoint of your Commerce Layer organization — to the CommerceLayer component, as follow:

<CommerceLayer
  accessToken="your-access-token"
  endpoint="https://yourdomain.commercelayer.io">

  {/* ... child components */}

</CommerceLayer>

This token will be used to authorize the API calls of all its child components. That's why the presence of (at least) one CommerceLayer component is mandatory — it must wrap every other component you need to use.

Please note that — in case you need to fetch data with different tokens (i.e. from different organizations or using apps with different roles and permissions) — nothing prevents you from putting as many CommerceLayer components you want in the same page.

You can check our documentation for more information about the available authorization flows and leverage Commerce Layer JS Auth to easily interact with our authentication API.

Import

You can use ES6 named import with every single component you plan to use (in addition to CommerceLayer one), as follow:

import { CommerceLayer, ...otherComponents } from '@commercelayer/react-components'

Check this summary table for the complete (and constantly updated) list of available components.

Usage

The code snippets below show how to put into action Commerce Layer React Components in some common use cases. Check the pages folder of this repository for more detailed examples.

• Prices
• Add to cart
• Shopping cart
• Cart summary

Under the hood, our React components are built on top of Commerce Layer JS SDK — feel free to use it if you want to develop your custom ones.

Prices

This example shows how to use Commerce Layer React Components to display the prices of some SKUs, identified by their SKU codes:

import {
  CommerceLayer,
  PricesContainer,
  Price
} from '@commercelayer/react-components'

// your code [...]

<CommerceLayer accessToken="your-access-token" endpoint="https://yourdomain.commercelayer.io">
  <PricesContainer>
    <Price
      skuCode="BABYONBU000000E63E7412MX"
      className="your-custom-class"
      compareClassName="your-custom-class"
    />
    <Price
      skuCode="CANVASAU000000FFFFFF1824"
      className="your-custom-class"
      compareClassName="your-custom-class"
    />
    <Price
      skuCode="LSLEEVMM000000E63E74LXXX"
      className="your-custom-class"
      compareClassName="your-custom-class"
    />
  </PricesContainer>
</CommerceLayer>

// your code [...]

You can style the selling price and the full price as you like by passing the className and compareClassName props to the Price component. You can choose not to show the full price by passing showCompare={false} (default is true).

If you need to paginate the list of prices, pass the perPage prop to the PricesContainer component (default is 10) — to learn how pagination works, check our API reference or our SDK documentation.

Add to cart

This example shows how to use Commerce Layer React Components to implement the "add to cart" functionality on your page, showing the price of the chosen SKU, the possibility to select a variant and its quantity, the information about its availability, and the related button to perform the action:

import {
  CommerceLayer,
  OrderContainer,
  OrderStorage,
  ItemContainer,
  PricesContainer,
  Price,
  VariantsContainer,
  VariantSelector,
  QuantitySelector,
  AddToCartButton,
  AvailabilityContainer,
  AvailabilityTemplate
} from '@commercelayer/react-components'

// your code [...]

<CommerceLayer accessToken="your-access-token" endpoint="https://yourdomain.commercelayer.io">
  <OrderStorage persistKey="your-persist-key">
    <OrderContainer
      attributes={{
        cart_url: 'https://yourdomain.com/cart',
        return_url: 'https://yourdomain.com/return',
        privacy_url: 'https://yourdomain.com/privacy'
      }}>
      <ItemContainer>
        <PricesContainer>
          <Price skuCode="BABYONBU000000E63E746MXX" />
        </PricesContainer>
        <VariantsContainer>
          <VariantSelector
            placeholder="Select a size"
            options={[
              {
                label: '6 months',
                code: 'BABYONBU000000E63E746MXX',
                lineItem: {
                  name: 'your-item-name',
                  imageUrl: 'https://img.yourdomain.com/your-item-image.png'
                }
              },
              {
                label: '12 months',
                code: 'BABYONBU000000E63E7412MX',
                lineItem: {
                  name: 'your-item-name',
                  imageUrl: 'https://img.yourdomain.com/your-item-image.png'
                }
              }
            ]}
          />
        </VariantsContainer>
        <QuantitySelector />
        <AddToCartButton />
        <AvailabilityContainer>
          <AvailabilityTemplate />
        </AvailabilityContainer>
      </ItemContainer>
    </OrderContainer>
  </OrderStorage>
</CommerceLayer>

// your code [...]

For each variant you can define the custom name (i.e. its translation based on location) and image that will be shown on the corresponding line item, by passing the options prop to the VariantSelector component and properly setting the lineItem key — all these content data are usually taken from your CMS, since Commerce Layer doesn't manage any kind of content. You can change the type of input by passing type="radio" (default is select).

When you add a product to your shopping cart:

• if there is an order stored in the Local Storage identified by a key that matches the persistKey property, a line item is created and it is associated with that order;
• if no order in the Local Storage matches the persistKey property, a new order is created and stored.

A common best practice — especially for multi-country ecommerce — is to use as persistKey a key containing the country code, so that you have a different shopping cart for each country.

If you need to set some of the order object attributes at the moment of the order creation, pass to the optional prop attributes to the OrderContainer component.

Shopping cart

This example shows how to use Commerce Layer React Components to build a shopping cart UI, containing the items that are going to be purchased with all their information (image, name, quantity, price) and the option to possibly remove some of them:

import {
  CommerceLayer,
  OrderContainer,
  OrderStorage,
  LineItemsContainer,
  LineItemsCount,
  LineItem,
  LineItemImage,
  LineItemName,
  LineItemQuantity,
  LineItemAmount,
  LineItemRemoveLink,
  Errors
} from '@commercelayer/react-components'

// your code [...]

<CommerceLayer accessToken="your-access-token" endpoint="https://yourdomain.commercelayer.io">
  <OrderStorage persistKey="your-persist-key">
      <OrderContainer>
        <LineItemsContainer>
          <p className="your-custom-class">
            Your shopping cart contains <LineItemsCount /> items
          </p>
          <LineItem>
            <LineItemImage width={50} />
            <LineItemName />
            <LineItemQuantity max={10} />
            <Errors resource="lineItem" field="quantity" />
            <LineItemAmount />
            <LineItemRemoveLink />
          </LineItem>
        </LineItemsContainer>
      </OrderContainer>
  </OrderStorage>
</CommerceLayer>

// your code [...]

The Errors component lets you show the error (if present) returned by our API on a single attribute of a specific resource. You can customize the error message as you like by passing the messages prop to the component.

Cart summary

This example shows how to use Commerce Layer React Components to show a sample order summary with all the order line items (including discounts, shipping costs, taxes, and gift cards — if present) and totals:

import {
  CommerceLayer,
  OrderContainer,
  OrderStorage,
  SubTotalAmount,
  DiscountAmount,
  ShippingAmount,
  TaxesAmount,
  GiftCardAmount,
  TotalAmount,
  CheckoutLink
} from '@commercelayer/react-components'

// your code [...]

<CommerceLayer accessToken="your-access-token" endpoint="https://yourdomain.commercelayer.io">
  <OrderStorage persistKey="your-persist-key">
    <OrderContainer>
      <SubTotalAmount />
      <DiscountAmount />
      <ShippingAmount />
      <TaxesAmount />
      <GiftCardAmount />
      <TotalAmount />
      <CheckoutLink />
    </OrderContainer>
  </OrderStorage>
</CommerceLayer>

// your code [...]

You can change the amount format of each line of the summary by passing the format prop to the desired component (default is formatted).

The CheckoutLink component lets you proceed to checkout and links to the checkout URL configured on Commerce Layer (Settings → Markets).

List of components

These are the currently available Commerce Layer React Components.

Please note that not every Commerce Layer React component can be nested into any other one.

For each component, the table below shows its props and the list of the permitted children (if any):

For more detailed information on each components (i.e. prop types and default values, required props, etc.), have a look at the configuration file src/config/components.ts.

License

This repository is published under the MIT license.